pltr-cli 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

pltr/services/functions.py

@@ -0,0 +1,223 @@
+"""
+Functions service wrapper for Foundry SDK.
+Provides access to Functions query execution and value type operations.
+"""
+
+from typing import Any, Dict, Optional
+from .base import BaseService
+
+
+class FunctionsService(BaseService):
+    """Service wrapper for Foundry Functions operations."""
+
+    def _get_service(self) -> Any:
+        """Get the Foundry Functions service."""
+        return self.client.functions
+
+    # ===== Query Operations =====
+
+    def get_query(
+        self,
+        query_api_name: str,
+        preview: bool = False,
+        version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get query metadata by API name.
+
+        Args:
+            query_api_name: Query API name (e.g., "myQuery")
+            preview: Enable preview mode (default: False)
+            version: Optional query version (e.g., "1.0.0")
+                If not specified, returns latest version
+
+        Returns:
+            Query information dictionary containing:
+            - rid: Query resource identifier
+            - apiName: Query API name
+            - version: Query version
+            - parameters: Query parameters with types
+            - output: Output structure definition
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = FunctionsService()
+            >>> query = service.get_query("myQuery")
+            >>> print(query['apiName'])
+        """
+        try:
+            query = self.service.Query.get(
+                query_api_name, preview=preview, version=version
+            )
+            return self._serialize_response(query)
+        except Exception as e:
+            raise RuntimeError(f"Failed to get query '{query_api_name}': {e}")
+
+    def get_query_by_rid(
+        self, query_rid: str, preview: bool = False, version: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Get query metadata by RID.
+
+        Args:
+            query_rid: Query Resource Identifier
+                Format: ri.functions.main.query.<id>
+            preview: Enable preview mode (default: False)
+            version: Optional query version (e.g., "1.0.0")
+                If not specified, returns latest version
+
+        Returns:
+            Query information dictionary containing:
+            - rid: Query resource identifier
+            - apiName: Query API name
+            - version: Query version
+            - parameters: Query parameters with types
+            - output: Output structure definition
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = FunctionsService()
+            >>> query = service.get_query_by_rid("ri.functions.main.query.abc123")
+            >>> print(query['rid'])
+        """
+        try:
+            query = self.service.Query.get_by_rid(
+                query_rid, preview=preview, version=version
+            )
+            return self._serialize_response(query)
+        except Exception as e:
+            raise RuntimeError(f"Failed to get query {query_rid}: {e}")
+
+    def execute_query(
+        self,
+        query_api_name: str,
+        parameters: Optional[Dict[str, Any]] = None,
+        preview: bool = False,
+        version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Execute a query by API name with parameters.
+
+        Args:
+            query_api_name: Query API name (e.g., "myQuery")
+            parameters: Query parameters as dictionary with DataValue encoding
+                Examples:
+                - Primitives: {"limit": 10, "name": "John"}
+                - Arrays: {"ids": [1, 2, 3]}
+                - Structs: {"config": {"enabled": true}}
+                - Dates: {"date": "2024-01-01"} (ISO 8601)
+                - Timestamps: {"created": "2021-01-04T05:00:00Z"} (ISO 8601)
+            preview: Enable preview mode (default: False)
+            version: Optional query version (e.g., "1.0.0")
+                If not specified, executes latest version
+
+        Returns:
+            Query execution result dictionary
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = FunctionsService()
+            >>> result = service.execute_query(
+            ...     "myQuery",
+            ...     parameters={"limit": 10, "filter": "active"}
+            ... )
+            >>> print(result)
+        """
+        try:
+            result = self.service.Query.execute(
+                query_api_name,
+                parameters=parameters or {},
+                preview=preview,
+                version=version,
+            )
+            return self._serialize_response(result)
+        except Exception as e:
+            raise RuntimeError(f"Failed to execute query '{query_api_name}': {e}")
+
+    def execute_query_by_rid(
+        self,
+        query_rid: str,
+        parameters: Optional[Dict[str, Any]] = None,
+        preview: bool = False,
+        version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Execute a query by RID with parameters.
+
+        Args:
+            query_rid: Query Resource Identifier
+                Format: ri.functions.main.query.<id>
+            parameters: Query parameters as dictionary with DataValue encoding
+                Examples:
+                - Primitives: {"limit": 10, "name": "John"}
+                - Arrays: {"ids": [1, 2, 3]}
+                - Structs: {"config": {"enabled": true}}
+                - Dates: {"date": "2024-01-01"} (ISO 8601)
+                - Timestamps: {"created": "2021-01-04T05:00:00Z"} (ISO 8601)
+            preview: Enable preview mode (default: False)
+            version: Optional query version (e.g., "1.0.0")
+                If not specified, executes latest version
+
+        Returns:
+            Query execution result dictionary
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = FunctionsService()
+            >>> result = service.execute_query_by_rid(
+            ...     "ri.functions.main.query.abc123",
+            ...     parameters={"limit": 10}
+            ... )
+            >>> print(result)
+        """
+        try:
+            result = self.service.Query.execute_by_rid(
+                query_rid,
+                parameters=parameters or {},
+                preview=preview,
+                version=version,
+            )
+            return self._serialize_response(result)
+        except Exception as e:
+            raise RuntimeError(f"Failed to execute query {query_rid}: {e}")
+
+    # ===== Value Type Operations =====
+
+    def get_value_type(
+        self, value_type_rid: str, preview: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Get value type details by RID.
+
+        Args:
+            value_type_rid: Value Type Resource Identifier
+                Format: ri.functions.main.value-type.<id>
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Value type information dictionary containing:
+            - rid: Value type resource identifier
+            - apiName: Value type API name
+            - definition: Type definition and structure
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = FunctionsService()
+            >>> value_type = service.get_value_type("ri.functions.main.value-type.xyz")
+            >>> print(value_type['apiName'])
+        """
+        try:
+            value_type = self.service.ValueType.get(value_type_rid, preview=preview)
+            return self._serialize_response(value_type)
+        except Exception as e:
+            raise RuntimeError(f"Failed to get value type {value_type_rid}: {e}")

pltr/services/language_models.py

@@ -0,0 +1,281 @@
+"""
+LanguageModels service wrapper for Foundry SDK.
+Provides access to Anthropic Claude models and OpenAI embeddings.
+"""
+
+from typing import Any, Dict, List, Optional
+from .base import BaseService
+
+
+class LanguageModelsService(BaseService):
+    """Service wrapper for Foundry LanguageModels operations."""
+
+    def _get_service(self) -> Any:
+        """Get the Foundry LanguageModels service."""
+        return self.client.language_models
+
+    # ===== Anthropic Model Operations =====
+
+    def send_message(
+        self,
+        model_id: str,
+        message: str,
+        max_tokens: int = 1024,
+        system: Optional[str] = None,
+        temperature: Optional[float] = None,
+        stop_sequences: Optional[List[str]] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Send a single message to an Anthropic model (simplified interface).
+
+        Args:
+            model_id: Model Resource Identifier
+                Format: ri.language-models.main.model.<id>
+            message: User message text
+            max_tokens: Maximum tokens to generate (default: 1024)
+            system: Optional system prompt to guide model behavior
+            temperature: Sampling temperature (0.0-1.0)
+                Lower values are more deterministic
+            stop_sequences: Optional list of sequences that stop generation
+            top_k: Sample from top K tokens (Anthropic models only)
+            top_p: Nucleus sampling threshold (0.0-1.0)
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Response dictionary containing:
+            - content: List of content blocks (text, tool use, etc.)
+            - role: Message role (typically "assistant")
+            - model: Model identifier
+            - stopReason: Reason generation stopped
+            - usage: Token usage statistics
+                - inputTokens: Input tokens consumed
+                - outputTokens: Output tokens generated
+                - totalTokens: Total tokens (input + output)
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = LanguageModelsService()
+            >>> response = service.send_message(
+            ...     "ri.language-models.main.model.abc123",
+            ...     "Explain quantum computing",
+            ...     max_tokens=200
+            ... )
+            >>> print(response['content'][0]['text'])
+        """
+        try:
+            # Transform simple message to SDK message format
+            messages = [
+                {
+                    "role": "user",
+                    "content": [{"type": "text", "text": message}],
+                }
+            ]
+
+            # Build request parameters
+            request_params: Dict[str, Any] = {
+                "messages": messages,
+                "maxTokens": max_tokens,
+            }
+
+            # Add optional parameters if provided
+            if system is not None:
+                request_params["system"] = [{"type": "text", "text": system}]
+            if temperature is not None:
+                request_params["temperature"] = temperature
+            if stop_sequences is not None:
+                request_params["stopSequences"] = stop_sequences
+            if top_k is not None:
+                request_params["topK"] = top_k
+            if top_p is not None:
+                request_params["topP"] = top_p
+
+            # Call SDK method
+            response = self.service.AnthropicModel.messages(
+                model_id,
+                request=request_params,
+                preview=preview,  # type: ignore
+            )
+
+            return self._serialize_response(response)
+        except Exception as e:
+            raise RuntimeError(f"Failed to send message to model {model_id}: {e}")
+
+    def send_messages_advanced(
+        self,
+        model_id: str,
+        messages: List[Dict[str, Any]],
+        max_tokens: int,
+        system: Optional[List[Dict[str, Any]]] = None,
+        temperature: Optional[float] = None,
+        thinking: Optional[Dict[str, Any]] = None,
+        tools: Optional[List[Dict[str, Any]]] = None,
+        tool_choice: Optional[Dict[str, Any]] = None,
+        stop_sequences: Optional[List[str]] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Send messages to an Anthropic model with advanced features.
+
+        This method accepts the full SDK request structure, enabling:
+        - Multi-turn conversations
+        - Tool/function calling
+        - Extended thinking mode
+        - Document and image processing
+        - Citations
+
+        Args:
+            model_id: Model Resource Identifier
+                Format: ri.language-models.main.model.<id>
+            messages: List of message objects with role and content
+                Format: [{"role": "user|assistant", "content": [...]}]
+            max_tokens: Maximum tokens to generate
+            system: Optional system prompt blocks
+                Format: [{"type": "text", "text": "..."}]
+            temperature: Sampling temperature (0.0-1.0)
+            thinking: Extended thinking configuration
+                Format: {"type": "enabled", "budget": 10000}
+            tools: Tool definitions for function calling
+            tool_choice: Tool selection strategy
+            stop_sequences: Sequences that stop generation
+            top_k: Sample from top K tokens
+            top_p: Nucleus sampling threshold (0.0-1.0)
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Response dictionary containing:
+            - content: List of content blocks (text, tool use, thinking, etc.)
+            - role: Message role (typically "assistant")
+            - model: Model identifier
+            - stopReason: Reason generation stopped
+            - usage: Token usage statistics
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = LanguageModelsService()
+            >>> messages = [
+            ...     {"role": "user", "content": [{"type": "text", "text": "Hi"}]},
+            ...     {"role": "assistant", "content": [{"type": "text", "text": "Hello!"}]},
+            ...     {"role": "user", "content": [{"type": "text", "text": "Help me"}]}
+            ... ]
+            >>> response = service.send_messages_advanced(
+            ...     "ri.language-models.main.model.abc123",
+            ...     messages=messages,
+            ...     max_tokens=500
+            ... )
+        """
+        try:
+            # Build request parameters
+            request_params: Dict[str, Any] = {
+                "messages": messages,
+                "maxTokens": max_tokens,
+            }
+
+            # Add optional parameters if provided
+            if system is not None:
+                request_params["system"] = system
+            if temperature is not None:
+                request_params["temperature"] = temperature
+            if thinking is not None:
+                request_params["thinking"] = thinking
+            if tools is not None:
+                request_params["tools"] = tools
+            if tool_choice is not None:
+                request_params["toolChoice"] = tool_choice
+            if stop_sequences is not None:
+                request_params["stopSequences"] = stop_sequences
+            if top_k is not None:
+                request_params["topK"] = top_k
+            if top_p is not None:
+                request_params["topP"] = top_p
+
+            # Call SDK method
+            response = self.service.AnthropicModel.messages(
+                model_id,
+                request=request_params,
+                preview=preview,  # type: ignore
+            )
+
+            return self._serialize_response(response)
+        except Exception as e:
+            raise RuntimeError(f"Failed to send messages to model {model_id}: {e}")
+
+    # ===== OpenAI Model Operations =====
+
+    def generate_embeddings(
+        self,
+        model_id: str,
+        input_texts: List[str],
+        dimensions: Optional[int] = None,
+        encoding_format: Optional[str] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Generate embeddings for text using an OpenAI model.
+
+        Args:
+            model_id: Model Resource Identifier
+                Format: ri.language-models.main.model.<id>
+            input_texts: List of text strings to embed
+                Can be a single string or multiple strings
+            dimensions: Optional custom embedding dimensions
+                Not all models support this parameter
+            encoding_format: Output encoding format
+                Options: "float" (default) or "base64"
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Response dictionary containing:
+            - data: List of embedding objects
+                Each object has:
+                - embedding: Vector (list of floats or base64 string)
+                - index: Position in input array
+                - object: Type identifier ("embedding")
+            - model: Model identifier
+            - usage: Token usage statistics
+                - promptTokens: Input tokens consumed
+                - totalTokens: Total tokens
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = LanguageModelsService()
+            >>> response = service.generate_embeddings(
+            ...     "ri.language-models.main.model.xyz789",
+            ...     input_texts=["Machine learning", "Deep learning"]
+            ... )
+            >>> embeddings = [item['embedding'] for item in response['data']]
+        """
+        try:
+            # Build request parameters
+            request_params: Dict[str, Any] = {
+                "input": input_texts,
+            }
+
+            # Add optional parameters if provided
+            if dimensions is not None:
+                request_params["dimensions"] = dimensions
+            if encoding_format is not None:
+                request_params["encodingFormat"] = encoding_format
+
+            # Call SDK method
+            response = self.service.OpenAiModel.embeddings(
+                model_id,
+                request=request_params,
+                preview=preview,  # type: ignore
+            )
+
+            return self._serialize_response(response)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to generate embeddings with model {model_id}: {e}"
+            )

pltr/services/mediasets.py

@@ -226,15 +226,7 @@ class MediaSetsService(BaseService):
                     preview=preview,
                 )
 
-            with open(output_path_obj, "wb") as file:
-                if hasattr(response, "content"):
-                    file.write(response.content)
-                else:
-                    # Handle streaming response
-                    for chunk in response:
-                        file.write(chunk)
-
-            file_size = output_path_obj.stat().st_size
+            file_size = self._write_response_to_file(response, output_path_obj)
             return {
                 "media_set_rid": media_set_rid,
                 "media_item_rid": media_item_rid,
@@ -291,3 +283,146 @@ class MediaSetsService(BaseService):
             "url": getattr(reference_response, "url", "unknown"),
             "expires_at": getattr(reference_response, "expires_at", None),
         }
+
+    def _write_response_to_file(self, response: Any, output_path: Path) -> int:
+        """
+        Write response content to file and return file size.
+
+        Args:
+            response: SDK response object (with .content attribute or iterable)
+            output_path: Path object for the output file
+
+        Returns:
+            File size in bytes
+        """
+        with open(output_path, "wb") as file:
+            if hasattr(response, "content"):
+                file.write(response.content)
+            else:
+                # Handle streaming response
+                for chunk in response:
+                    file.write(chunk)
+        return output_path.stat().st_size
+
+    def calculate_thumbnail(
+        self,
+        media_set_rid: str,
+        media_item_rid: str,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Initiate thumbnail generation for an image.
+
+        Args:
+            media_set_rid: Media Set Resource Identifier
+            media_item_rid: Media Item Resource Identifier
+            preview: Enable preview mode
+
+        Returns:
+            Thumbnail calculation status information
+        """
+        try:
+            response = self.service.MediaSet.calculate(
+                media_set_rid=media_set_rid,
+                media_item_rid=media_item_rid,
+                preview=preview,
+            )
+            return self._format_thumbnail_status(response)
+        except Exception as e:
+            raise RuntimeError(f"Failed to calculate thumbnail: {e}")
+
+    def retrieve_thumbnail(
+        self,
+        media_set_rid: str,
+        media_item_rid: str,
+        output_path: str,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Retrieve a calculated thumbnail (200px wide webp).
+
+        Args:
+            media_set_rid: Media Set Resource Identifier
+            media_item_rid: Media Item Resource Identifier
+            output_path: Local path where thumbnail should be saved
+            preview: Enable preview mode
+
+        Returns:
+            Download response information
+        """
+        try:
+            output_path_obj = Path(output_path)
+            output_path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+            response = self.service.MediaSet.retrieve(
+                media_set_rid=media_set_rid,
+                media_item_rid=media_item_rid,
+                preview=preview,
+            )
+
+            file_size = self._write_response_to_file(response, output_path_obj)
+
+            # Validate that we received actual content
+            if file_size == 0:
+                output_path_obj.unlink(missing_ok=True)
+                raise RuntimeError(
+                    "Downloaded thumbnail is empty - thumbnail may not be ready yet"
+                )
+
+            return {
+                "media_set_rid": media_set_rid,
+                "media_item_rid": media_item_rid,
+                "output_path": str(output_path_obj),
+                "file_size": file_size,
+                "downloaded": True,
+                "format": "image/webp",
+            }
+        except Exception as e:
+            raise RuntimeError(f"Failed to retrieve thumbnail: {e}")
+
+    def upload_temp_media(
+        self,
+        file_path: str,
+        filename: Optional[str] = None,
+        attribution: Optional[str] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Upload temporary media (auto-deleted after 1 hour if not persisted).
+
+        Args:
+            file_path: Local path to the file to upload
+            filename: Optional filename override
+            attribution: Optional attribution string
+            preview: Enable preview mode
+
+        Returns:
+            Media reference information
+        """
+        try:
+            file_path_obj = Path(file_path)
+            if not file_path_obj.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            # Use provided filename or default to file name
+            upload_filename = filename or file_path_obj.name
+
+            with open(file_path_obj, "rb") as file:
+                response = self.service.MediaSet.upload_media(
+                    body=file,
+                    filename=upload_filename,
+                    attribution=attribution,
+                    preview=preview,
+                )
+
+            return self._format_media_reference(response)
+        except Exception as e:
+            raise RuntimeError(f"Failed to upload temporary media: {e}")
+
+    def _format_thumbnail_status(self, status_response: Any) -> Dict[str, Any]:
+        """Format thumbnail calculation status response for display."""
+        return {
+            "status": getattr(status_response, "status", "unknown"),
+            "transformation_id": getattr(status_response, "transformation_id", None),
+            "media_item_rid": getattr(status_response, "media_item_rid", None),
+        }