plansolve 0.25.0__py3-none-any.whl

plansolve/__init__.py

@@ -0,0 +1,66 @@
+"""
+PlanSolve Python SDK
+
+A Python client library for the PlanSolve optimization API.
+"""
+
+from .client import PlanSolveClient
+from .field_service.constraint_weight import ConstraintWeight
+from .field_service.api_client import FieldServiceApiClient
+from .professional_services.api_client import ProfessionalServicesApiClient
+
+# Field Service Models
+from .field_service.models import (
+    Shift,
+    TimeWindow,
+    Vehicle,
+    Visit,
+    SolverOptions,
+    Weights,
+    FieldServiceRequest,
+    ScheduledVehicle,
+    ScheduledVisit,
+    FieldServiceResponse,
+    FieldServiceResultResponse,
+)
+
+# Professional Services Models
+from .professional_services.models import (
+    Employee,
+    Task,
+    ProfessionalServicesRequest,
+    ScheduledEmployee,
+    ScheduledTask,
+    ProfessionalServicesResponse,
+    ProfessionalServicesResultResponse,
+)
+
+__version__ = "0.25.0"
+
+__all__ = [
+    "PlanSolveClient",
+    "FieldServiceApiClient",
+    "ProfessionalServicesApiClient",
+    "ConstraintWeight",
+    # Field Service Models
+    "Shift",
+    "TimeWindow",
+    "Vehicle",
+    "Visit",
+    "SolverOptions",
+    "Weights",
+    "FieldServiceRequest",
+    "ScheduledVehicle",
+    "ScheduledVisit",
+    "FieldServiceResponse",
+    "FieldServiceResultResponse",
+    # Professional Services Models
+    "Employee",
+    "Task",
+    "ProfessionalServicesRequest",
+    "ScheduledEmployee",
+    "ScheduledTask",
+    "ProfessionalServicesResponse",
+    "ProfessionalServicesResultResponse",
+]
+

plansolve/client.py

@@ -0,0 +1,40 @@
+"""Main PlanSolve client class."""
+
+from typing import Optional
+
+from .field_service.api_client import FieldServiceApiClient
+from .professional_services.api_client import ProfessionalServicesApiClient
+from .shift.api_client import ShiftApiClient
+
+
+class PlanSolveClient:
+    """Main client class for interacting with the PlanSolve API."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize the PlanSolve client.
+
+        Args:
+            api_key: Optional API key for authenticated requests
+        """
+        self.field_service = FieldServiceApiClient(api_key)
+        self.professional_services = ProfessionalServicesApiClient(api_key)
+        self.shift = ShiftApiClient(api_key)
+
+    def get_status(self, job_id: str) -> dict:
+        """
+        Get the status of a running optimization job.
+
+        Args:
+            job_id: The job ID to check status for
+
+        Returns:
+            Status response dictionary
+
+        Note:
+            This method uses the field service endpoint for status checking.
+            For professional services, use professional_services.get_status() instead.
+        """
+        return self.field_service.get_status(job_id)
+
+

plansolve/field_service/__init__.py

@@ -0,0 +1,34 @@
+"""Field service optimization module."""
+
+from .api_client import FieldServiceApiClient
+from .constraint_weight import ConstraintWeight
+from .models import (
+    Shift,
+    TimeWindow,
+    Vehicle,
+    Visit,
+    SolverOptions,
+    Weights,
+    FieldServiceRequest,
+    ScheduledVehicle,
+    ScheduledVisit,
+    FieldServiceResponse,
+    FieldServiceResultResponse,
+)
+
+__all__ = [
+    "FieldServiceApiClient",
+    "ConstraintWeight",
+    "Shift",
+    "TimeWindow",
+    "Vehicle",
+    "Visit",
+    "SolverOptions",
+    "Weights",
+    "FieldServiceRequest",
+    "ScheduledVehicle",
+    "ScheduledVisit",
+    "FieldServiceResponse",
+    "FieldServiceResultResponse",
+]
+

plansolve/field_service/api_client.py

@@ -0,0 +1,212 @@
+"""Field service API client."""
+
+import time
+from typing import Any, Dict, Optional, Union
+
+import requests
+
+from ..routes import Routes
+from ..solver_status import SOLVER_STATUS, SolverStatusResponse
+from .models import (
+    FieldServiceRequest,
+    FieldServiceResponse,
+    FieldServiceResultResponse,
+)
+
+
+class FieldServiceApiClient:
+    """Client for field service optimization API."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize the field service API client.
+
+        Args:
+            api_key: Optional API key for authenticated requests
+        """
+        self.base_url = f"https://plansolve.app{Routes.FIELD_SERVICE_SOLVE}"
+        self.api_key = api_key
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get request headers with optional API key."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        return headers
+
+    def start(
+        self, request: Union[FieldServiceRequest, Dict[str, Any]]
+    ) -> FieldServiceResponse:
+        """
+        Start a new field service optimization.
+
+        Args:
+            request: Field service request (FieldServiceRequest dataclass or dict)
+
+        Returns:
+            FieldServiceResponse with jobId, solverJobId, result, and error
+
+        Raises:
+            requests.RequestException: If the API request fails
+        """
+        # Convert dataclass to dict if needed
+        if isinstance(request, FieldServiceRequest):
+            api_request = request.to_dict()
+        else:
+            api_request = request
+
+        response = requests.post(
+            self.base_url, json=api_request, headers=self._get_headers()
+        )
+        response.raise_for_status()
+        return FieldServiceResponse.from_dict(response.json())
+
+    def get_result(self, job_id: str) -> FieldServiceResultResponse:
+        """
+        Get the completed optimization result.
+
+        Args:
+            job_id: The job ID to get results for
+
+        Returns:
+            FieldServiceResultResponse with vehicles, visits, score, etc.
+
+        Raises:
+            requests.RequestException: If the API request fails
+        """
+        url = f"{self.base_url}/{job_id}"
+        headers = {}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        return FieldServiceResultResponse.from_dict(response.json())
+
+    def get_status(self, job_id: str) -> SolverStatusResponse:
+        """
+        Get the status of a running optimization job.
+
+        Args:
+            job_id: The job ID to check status for
+
+        Returns:
+            Status response dictionary
+
+        Raises:
+            requests.RequestException: If the API request fails
+        """
+        url = f"{self.base_url}/{job_id}/status"
+        headers = {}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+
+    def analyze(self, job_id: str) -> Dict[str, Any]:
+        """
+        Get analysis for a completed optimization job.
+
+        Args:
+            job_id: The job ID to get analysis for
+
+        Returns:
+            Analysis response dictionary
+
+        Raises:
+            requests.RequestException: If the API request fails
+        """
+        url = f"{self.base_url}/{job_id}/analyze"
+        headers = {}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+
+    def start_and_wait_for_completion(
+        self,
+        request: Union[FieldServiceRequest, Dict[str, Any]],
+        poll_interval_ms: int = 5000,
+        max_attempts: int = 10,
+    ) -> FieldServiceResultResponse:
+        """
+        Start a job and wait for completion, polling for status.
+        Matches the logic used in the .NET SDK implementation exactly.
+
+        Args:
+            request: Field service request (FieldServiceRequest dataclass or dict)
+            poll_interval_ms: Milliseconds to wait between status checks
+            max_attempts: Maximum number of polling attempts
+
+        Returns:
+            FieldServiceResultResponse with optimization results
+
+        Raises:
+            ValueError: If jobId is not returned or solver times out
+            requests.RequestException: If API requests fail
+        """
+        start_response = self.start(request)
+        return self.wait_for_completion(start_response.job_id, poll_interval_ms, max_attempts)
+
+    def wait_for_completion(
+        self,
+        job_id: str,
+        poll_interval_ms: int = 5000,
+        max_attempts: int = 10,
+    ) -> FieldServiceResultResponse:
+        """
+        Wait for a job to complete, polling for status.
+        Matches the logic used in the .NET SDK implementation exactly.
+
+        Args:
+            job_id: The job ID to wait for
+            poll_interval_ms: Milliseconds to wait between status checks
+            max_attempts: Maximum number of polling attempts
+
+        Returns:
+            FieldServiceResultResponse with optimization results
+
+        Raises:
+            ValueError: If jobId is not provided or solver times out
+            requests.RequestException: If API requests fail
+        """
+        if not job_id:
+            raise ValueError("JobId was not returned from wait_for_completion.")
+
+        attempts = 0
+        status: SolverStatusResponse
+
+        while True:
+            time.sleep(poll_interval_ms / 1000.0)  # Convert ms to seconds
+            status = self.get_status(job_id)
+            attempts += 1
+
+            if not self._is_still_solving(status) or attempts >= max_attempts:
+                break
+
+        if self._is_still_solving(status):
+            raise ValueError("Solver did not finish in the allotted time.")
+
+        return self.get_result(job_id)
+
+    def _is_still_solving(self, status: SolverStatusResponse) -> bool:
+        """
+        Determine if the solver is still running based on the status response.
+        Matches the logic used in the .NET SDK implementation exactly.
+
+        Args:
+            status: Status response dictionary
+
+        Returns:
+            True if still solving, False otherwise
+        """
+        # Match .NET logic: status.Solving || status.SolverStatus == SolverStatus.SOLVING_SCHEDULED ||
+        # (status.SolverStatus != SolverStatus.NOT_SOLVING) || string.IsNullOrEmpty(status.Score)
+        return (
+            status.get("solving", False)
+            or status.get("solverStatus") == SOLVER_STATUS["SOLVING_SCHEDULED"]
+            or status.get("solverStatus") != SOLVER_STATUS["NOT_SOLVING"]
+            or not status.get("score")
+        )
+

plansolve/field_service/constraint_weight.py

@@ -0,0 +1,143 @@
+"""Constraint weight representation for field service optimization."""
+
+import re
+from typing import Optional
+
+
+class ConstraintWeight:
+    """
+    Represents a constraint weight in the format "Xhard/Ymedium/Zsoft" where X, Y, Z are numeric values.
+    Only one of hard, medium, or soft can be non-zero at a time.
+    Examples: "1hard/0medium/0soft", "0hard/1medium/0soft", "0hard/0medium/1soft"
+    """
+
+    def __init__(self, hard: int, medium: int, soft: int):
+        """
+        Create a new ConstraintWeight with the specified values.
+        Only one of hard, medium, or soft can be non-zero.
+
+        Args:
+            hard: Hard constraint weight value
+            medium: Medium constraint weight value
+            soft: Soft constraint weight value
+
+        Raises:
+            ValueError: When more than one value is non-zero
+        """
+        non_zero_count = sum(1 for x in [hard, medium, soft] if x != 0)
+        if non_zero_count > 1:
+            raise ValueError(
+                f"Only one of hard, medium, or soft can be non-zero. "
+                f"Received: hard={hard}, medium={medium}, soft={soft}"
+            )
+
+        self.hard = hard
+        self.medium = medium
+        self.soft = soft
+
+    @staticmethod
+    def parse(value: str) -> "ConstraintWeight":
+        """
+        Parse a weight string in the format "Xhard/Ymedium/Zsoft".
+        Only one of X, Y, or Z can be non-zero.
+
+        Args:
+            value: The weight string to parse
+
+        Returns:
+            A ConstraintWeight instance
+
+        Raises:
+            ValueError: When the string format is invalid or more than one value is non-zero
+        """
+        if not value or not value.strip():
+            raise ValueError("Weight value cannot be null or empty")
+
+        # Pattern: (\d+)hard/(\d+)medium/(\d+)soft
+        pattern = r"^(\d+)hard/(\d+)medium/(\d+)soft$"
+        match = re.match(pattern, value, re.IGNORECASE)
+
+        if not match:
+            raise ValueError(
+                f"Invalid weight format: '{value}'. Expected format: 'Xhard/Ymedium/Zsoft'"
+            )
+
+        hard = int(match.group(1))
+        medium = int(match.group(2))
+        soft = int(match.group(3))
+
+        return ConstraintWeight(hard, medium, soft)
+
+    @staticmethod
+    def try_parse(value: Optional[str]) -> Optional["ConstraintWeight"]:
+        """
+        Attempt to parse a weight string. Returns the ConstraintWeight if successful, None otherwise.
+
+        Args:
+            value: The weight string to parse, or None
+
+        Returns:
+            ConstraintWeight instance if successful, None otherwise
+        """
+        if not value or not value.strip():
+            return None
+
+        try:
+            return ConstraintWeight.parse(value)
+        except (ValueError, AttributeError):
+            return None
+
+    def __str__(self) -> str:
+        """
+        Return the string representation in the format "Xhard/Ymedium/Zsoft".
+
+        Returns:
+            String representation of the weight
+        """
+        return f"{self.hard}hard/{self.medium}medium/{self.soft}soft"
+
+    def __repr__(self) -> str:
+        """Return a string representation of the ConstraintWeight."""
+        return f"ConstraintWeight(hard={self.hard}, medium={self.medium}, soft={self.soft})"
+
+    @staticmethod
+    def create_hard(value: int) -> "ConstraintWeight":
+        """
+        Create a hard constraint weight (Xhard/0medium/0soft).
+
+        Args:
+            value: The hard constraint value
+
+        Returns:
+            ConstraintWeight instance
+        """
+        return ConstraintWeight(value, 0, 0)
+
+    @staticmethod
+    def create_medium(value: int) -> "ConstraintWeight":
+        """
+        Create a medium constraint weight (0hard/Xmedium/0soft).
+
+        Args:
+            value: The medium constraint value
+
+        Returns:
+            ConstraintWeight instance
+        """
+        return ConstraintWeight(0, value, 0)
+
+    @staticmethod
+    def create_soft(value: int) -> "ConstraintWeight":
+        """
+        Create a soft constraint weight (0hard/0medium/Xsoft).
+
+        Args:
+            value: The soft constraint value
+
+        Returns:
+            ConstraintWeight instance
+        """
+        return ConstraintWeight(0, 0, value)
+
+
+