pltr-cli 0.12.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/models.py

@@ -0,0 +1,179 @@
+"""
+Models service wrapper for Foundry SDK.
+Provides access to ML model registry operations (model lifecycle, versioning, metadata).
+
+Note: This is distinct from LanguageModels, which handles LLM chat/embeddings operations.
+"""
+
+from typing import Any, Dict, Optional
+from .base import BaseService
+
+
+class ModelsService(BaseService):
+    """Service wrapper for Foundry Models operations."""
+
+    def _get_service(self) -> Any:
+        """Get the Foundry Models service."""
+        return self.client.models
+
+    # ===== Model Operations =====
+
+    def create_model(
+        self,
+        name: str,
+        parent_folder_rid: str,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Create a new ML model in the registry.
+
+        Args:
+            name: Model name
+            parent_folder_rid: Parent folder RID (e.g., ri.compass.main.folder.xxx)
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Model information dictionary containing:
+            - rid: Model resource identifier
+            - name: Model name
+            - parentFolderRid: Parent folder RID
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = ModelsService()
+            >>> model = service.create_model(
+            ...     name="fraud-detector",
+            ...     parent_folder_rid="ri.compass.main.folder.xxx"
+            ... )
+        """
+        try:
+            model = self.service.Model.create(
+                name=name,
+                parent_folder_rid=parent_folder_rid,
+                preview=preview,
+            )
+            return self._serialize_response(model)
+        except Exception as e:
+            raise RuntimeError(f"Failed to create model '{name}': {e}")
+
+    def get_model(
+        self,
+        model_rid: str,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Get information about a model.
+
+        Args:
+            model_rid: Model RID (e.g., ri.foundry.main.model.xxx)
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Model information dictionary
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = ModelsService()
+            >>> model = service.get_model(
+            ...     model_rid="ri.foundry.main.model.abc123"
+            ... )
+        """
+        try:
+            model = self.service.Model.get(
+                model_rid=model_rid,
+                preview=preview,
+            )
+            return self._serialize_response(model)
+        except Exception as e:
+            raise RuntimeError(f"Failed to get model '{model_rid}': {e}")
+
+    # ===== ModelVersion Operations =====
+
+    def get_model_version(
+        self,
+        model_rid: str,
+        model_version_rid: str,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Get information about a specific model version.
+
+        Args:
+            model_rid: Model RID (e.g., ri.foundry.main.model.xxx)
+            model_version_rid: Version identifier (e.g., v1.0.0 or version RID)
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Model version information dictionary
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = ModelsService()
+            >>> version = service.get_model_version(
+            ...     model_rid="ri.foundry.main.model.abc123",
+            ...     model_version_rid="v1.0.0"
+            ... )
+        """
+        try:
+            version = self.service.ModelVersion.get(
+                model_rid=model_rid,
+                model_version_rid=model_version_rid,
+                preview=preview,
+            )
+            return self._serialize_response(version)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to get model version '{model_version_rid}' for model '{model_rid}': {e}"
+            )
+
+    def list_model_versions(
+        self,
+        model_rid: str,
+        page_size: Optional[int] = None,
+        page_token: Optional[str] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        List all versions of a model with pagination support.
+
+        Args:
+            model_rid: Model RID (e.g., ri.foundry.main.model.xxx)
+            page_size: Maximum number of versions to return per page
+            page_token: Token for fetching next page of results
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Dictionary containing:
+            - data: List of model version information dictionaries
+            - nextPageToken: Token for next page (if available)
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = ModelsService()
+            >>> result = service.list_model_versions(
+            ...     model_rid="ri.foundry.main.model.abc123",
+            ...     page_size=50
+            ... )
+            >>> versions = result['data']
+            >>> next_token = result.get('nextPageToken')
+        """
+        try:
+            response = self.service.ModelVersion.list(
+                model_rid=model_rid,
+                page_size=page_size,
+                page_token=page_token,
+                preview=preview,
+            )
+            return self._serialize_response(response)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to list model versions for model '{model_rid}': {e}"
+            )