plansolve 0.25.0__py3-none-any.whl

plansolve/field_service/models.py

@@ -0,0 +1,427 @@
+"""Data models for field service optimization."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple, Dict, Any, Literal
+
+from .constraint_weight import ConstraintWeight
+
+
+@dataclass
+class Shift:
+    """Represents a work shift for a vehicle."""
+
+    id: str
+    min_start_time: str  # ISO 8601 datetime string
+    max_end_time: str  # ISO 8601 datetime string
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        return {
+            "id": self.id,
+            "minStartTime": self.min_start_time,
+            "maxEndTime": self.max_end_time,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Shift":
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            min_start_time=data["minStartTime"],
+            max_end_time=data["maxEndTime"],
+        )
+
+
+@dataclass
+class TimeWindow:
+    """Represents a time window for a visit."""
+
+    min_start_time: str  # ISO 8601 datetime string
+    max_end_time: str  # ISO 8601 datetime string
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        return {
+            "minStartTime": self.min_start_time,
+            "maxEndTime": self.max_end_time,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TimeWindow":
+        """Create from dictionary."""
+        return cls(
+            min_start_time=data["minStartTime"],
+            max_end_time=data["maxEndTime"],
+        )
+
+
+@dataclass
+class Vehicle:
+    """Represents a vehicle (field technician) for optimization."""
+
+    id: str
+    location: Tuple[float, float]  # [latitude, longitude]
+    shifts: List[Shift]
+    skills: List[str] = field(default_factory=list)
+    name: Optional[str] = None
+    departure_time: Optional[str] = None
+    visits: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        result = {
+            "id": self.id,
+            "location": list(self.location),
+            "shifts": [shift.to_dict() for shift in self.shifts],
+            "skills": self.skills,
+        }
+        if self.name is not None:
+            result["name"] = self.name
+        if self.departure_time is not None:
+            result["departureTime"] = self.departure_time
+        if self.visits is not None:
+            result["visits"] = self.visits
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Vehicle":
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            location=tuple(data["location"]),
+            shifts=[Shift.from_dict(s) for s in data["shifts"]],
+            skills=data.get("skills", []),
+            name=data.get("name"),
+            departure_time=data.get("departureTime"),
+            visits=data.get("visits"),
+        )
+
+
+@dataclass
+class Visit:
+    """Represents a visit (customer appointment) for optimization."""
+
+    id: str
+    name: str
+    location: Tuple[float, float]  # [latitude, longitude]
+    time_windows: List[TimeWindow]
+    service_duration: str  # ISO 8601 duration string
+    priority: Literal["HIGH", "MEDIUM", "LOW"]
+    required_skills: List[str] = field(default_factory=list)
+    pinned: bool = False
+    vehicle: Optional[str] = None
+    arrival_time: Optional[str] = None
+    departure_time: Optional[str] = None
+    start_service_time: Optional[str] = None
+    driving_time_seconds_from_previous_standstill: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        result = {
+            "id": self.id,
+            "name": self.name,
+            "location": list(self.location),
+            "timeWindows": [tw.to_dict() for tw in self.time_windows],
+            "serviceDuration": self.service_duration,
+            "priority": self.priority,
+            "requiredSkills": self.required_skills,
+            "pinned": self.pinned,
+        }
+        if self.vehicle is not None:
+            result["vehicle"] = self.vehicle
+        if self.arrival_time is not None:
+            result["arrivalTime"] = self.arrival_time
+        if self.departure_time is not None:
+            result["departureTime"] = self.departure_time
+        if self.start_service_time is not None:
+            result["startServiceTime"] = self.start_service_time
+        if self.driving_time_seconds_from_previous_standstill is not None:
+            result["drivingTimeSecondsFromPreviousStandstill"] = self.driving_time_seconds_from_previous_standstill
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Visit":
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            location=tuple(data["location"]),
+            time_windows=[TimeWindow.from_dict(tw) for tw in data["timeWindows"]],
+            service_duration=data["serviceDuration"],
+            priority=data["priority"],
+            required_skills=data.get("requiredSkills", []),
+            pinned=data.get("pinned", False),
+            vehicle=data.get("vehicle"),
+            arrival_time=data.get("arrivalTime"),
+            departure_time=data.get("departureTime"),
+            start_service_time=data.get("startServiceTime"),
+            driving_time_seconds_from_previous_standstill=data.get("drivingTimeSecondsFromPreviousStandstill"),
+        )
+
+
+@dataclass
+class SolverOptions:
+    """Solver options for field service optimization."""
+
+    spent_limit: Optional[str] = None  # ISO-8601 duration format, e.g., "PT5M"
+    unimproved_spent_limit: Optional[str] = None  # ISO-8601 duration format
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        result = {}
+        if self.spent_limit is not None:
+            result["spentLimit"] = self.spent_limit
+        if self.unimproved_spent_limit is not None:
+            result["unimprovedSpentLimit"] = self.unimproved_spent_limit
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SolverOptions":
+        """Create from dictionary."""
+        return cls(
+            spent_limit=data.get("spentLimit"),
+            unimproved_spent_limit=data.get("unimprovedSpentLimit"),
+        )
+
+
+@dataclass
+class Weights:
+    """Configuration weights for field service optimization constraints."""
+
+    pinned_visit_vehicle_assignment: Optional[ConstraintWeight] = None
+    pinned_visit_service_time: Optional[ConstraintWeight] = None
+    no_missing_skills: Optional[ConstraintWeight] = None
+    service_time_missing: Optional[ConstraintWeight] = None
+    vehicle_unassigned: Optional[ConstraintWeight] = None
+    prefer_high_priority: Optional[ConstraintWeight] = None
+    minimize_travel_time: Optional[ConstraintWeight] = None
+    prefer_using_idle_vehicles: Optional[ConstraintWeight] = None
+    minimize_early_arrival_wait: Optional[ConstraintWeight] = None
+    prefer_initial_vehicle_assignment: Optional[ConstraintWeight] = None
+    prefer_earlier_visit_dates: Optional[ConstraintWeight] = None
+
+    def to_dict(self) -> Dict[str, str]:
+        """Convert to dictionary for API serialization."""
+        result = {}
+        if self.pinned_visit_vehicle_assignment is not None:
+            result["pinnedVisitVehicleAssignment"] = str(
+                self.pinned_visit_vehicle_assignment
+            )
+        if self.pinned_visit_service_time is not None:
+            result["pinnedVisitServiceTime"] = str(self.pinned_visit_service_time)
+        if self.no_missing_skills is not None:
+            result["noMissingSkills"] = str(self.no_missing_skills)
+        if self.service_time_missing is not None:
+            result["serviceTimeMissing"] = str(self.service_time_missing)
+        if self.vehicle_unassigned is not None:
+            result["vehicleUnassigned"] = str(self.vehicle_unassigned)
+        if self.prefer_high_priority is not None:
+            result["preferHighPriority"] = str(self.prefer_high_priority)
+        if self.minimize_travel_time is not None:
+            result["minimizeTravelTime"] = str(self.minimize_travel_time)
+        if self.prefer_using_idle_vehicles is not None:
+            result["preferUsingIdleVehicles"] = str(self.prefer_using_idle_vehicles)
+        if self.minimize_early_arrival_wait is not None:
+            result["minimizeEarlyArrivalWait"] = str(self.minimize_early_arrival_wait)
+        if self.prefer_initial_vehicle_assignment is not None:
+            result["preferInitialVehicleAssignment"] = str(
+                self.prefer_initial_vehicle_assignment
+            )
+        if self.prefer_earlier_visit_dates is not None:
+            result["PreferEarlierVisitDates"] = str(self.prefer_earlier_visit_dates)
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Weights":
+        """Create from dictionary."""
+        from .constraint_weight import ConstraintWeight
+
+        def parse_weight(value: Any) -> Optional[ConstraintWeight]:
+            if value is None:
+                return None
+            if isinstance(value, ConstraintWeight):
+                return value
+            if isinstance(value, str):
+                return ConstraintWeight.try_parse(value)
+            return None
+
+        return cls(
+            pinned_visit_vehicle_assignment=parse_weight(
+                data.get("pinnedVisitVehicleAssignment")
+            ),
+            pinned_visit_service_time=parse_weight(data.get("pinnedVisitServiceTime")),
+            no_missing_skills=parse_weight(data.get("noMissingSkills")),
+            service_time_missing=parse_weight(data.get("serviceTimeMissing")),
+            vehicle_unassigned=parse_weight(data.get("vehicleUnassigned")),
+            prefer_high_priority=parse_weight(data.get("preferHighPriority")),
+            minimize_travel_time=parse_weight(data.get("minimizeTravelTime")),
+            prefer_using_idle_vehicles=parse_weight(
+                data.get("preferUsingIdleVehicles")
+            ),
+            minimize_early_arrival_wait=parse_weight(
+                data.get("minimizeEarlyArrivalWait")
+            ),
+            prefer_initial_vehicle_assignment=parse_weight(
+                data.get("preferInitialVehicleAssignment")
+            ),
+            prefer_earlier_visit_dates=parse_weight(
+                data.get("PreferEarlierVisitDates")
+            ),
+        )
+
+
+@dataclass
+class FieldServiceRequest:
+    """Request for field service optimization."""
+
+    vehicles: List[Vehicle]
+    visits: List[Visit]
+    weights: Optional[Weights] = None
+    options: Optional[SolverOptions] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for API serialization."""
+        result = {
+            "vehicles": [v.to_dict() for v in self.vehicles],
+            "visits": [v.to_dict() for v in self.visits],
+        }
+        if self.weights is not None:
+            weights_dict = self.weights.to_dict()
+            if weights_dict:
+                result["weights"] = weights_dict
+        if self.options is not None:
+            options_dict = self.options.to_dict()
+            if options_dict:
+                result["options"] = options_dict
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FieldServiceRequest":
+        """Create from dictionary."""
+        return cls(
+            vehicles=[Vehicle.from_dict(v) for v in data["vehicles"]],
+            visits=[Visit.from_dict(v) for v in data["visits"]],
+            weights=Weights.from_dict(data["weights"]) if data.get("weights") else None,
+            options=(
+                SolverOptions.from_dict(data["options"])
+                if data.get("options")
+                else None
+            ),
+        )
+
+
+@dataclass
+class ScheduledVehicle:
+    """Scheduled vehicle with assigned visits."""
+
+    id: str
+    location: Tuple[float, float]
+    shifts: List[Shift]
+    skills: List[str]
+    visits: List[str]  # List of visit IDs
+    daily_return_times: Optional[Dict[str, Any]] = None
+    total_driving_time_seconds: Optional[int] = None
+    arrival_time: Optional[str] = None
+    departure_time: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ScheduledVehicle":
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            location=tuple(data["location"]),
+            shifts=[Shift.from_dict(s) for s in data["shifts"]],
+            skills=data.get("skills", []),
+            visits=data.get("visits", []),
+            daily_return_times=data.get("dailyReturnTimes"),
+            total_driving_time_seconds=data.get("totalDrivingTimeSeconds"),
+            arrival_time=data.get("arrivalTime"),
+            departure_time=data.get("departureTime"),
+        )
+
+
+@dataclass
+class ScheduledVisit:
+    """Scheduled visit with timing information."""
+
+    id: str
+    name: str
+    location: Tuple[float, float]
+    time_windows: List[TimeWindow]
+    service_duration: str
+    priority: Literal["HIGH", "MEDIUM", "LOW"]
+    required_skills: List[str]
+    vehicle: str
+    previous_visit: Optional[str]
+    arrival_time: str
+    departure_time: str
+    start_service_time: str
+    driving_time_seconds_from_previous_standstill: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ScheduledVisit":
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            location=tuple(data["location"]),
+            time_windows=[TimeWindow.from_dict(tw) for tw in data["timeWindows"]],
+            service_duration=data["serviceDuration"],
+            priority=data["priority"],
+            required_skills=data.get("requiredSkills", []),
+            vehicle=data["vehicle"],
+            previous_visit=data.get("previousVisit"),
+            arrival_time=data["arrivalTime"],
+            departure_time=data["departureTime"],
+            start_service_time=data["startServiceTime"],
+            driving_time_seconds_from_previous_standstill=data[
+                "drivingTimeSecondsFromPreviousStandstill"
+            ],
+        )
+
+
+@dataclass
+class FieldServiceResponse:
+    """Response from starting a field service optimization."""
+
+    job_id: str
+    solver_job_id: str
+    result: str
+    error: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FieldServiceResponse":
+        """Create from dictionary."""
+        return cls(
+            job_id=data["jobId"],
+            solver_job_id=data["solverJobId"],
+            result=data["result"],
+            error=data.get("error"),
+        )
+
+
+@dataclass
+class FieldServiceResultResponse:
+    """Result response from a completed field service optimization."""
+
+    vehicles: List[ScheduledVehicle]
+    visits: List[ScheduledVisit]
+    score: Optional[str] = None
+    total_driving_time_seconds: int = 0
+    weights: Optional[Dict[str, Any]] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FieldServiceResultResponse":
+        """Create from dictionary."""
+        return cls(
+            vehicles=[
+                ScheduledVehicle.from_dict(v) for v in data.get("vehicles", [])
+            ],
+            visits=[ScheduledVisit.from_dict(v) for v in data.get("visits", [])],
+            score=data.get("score"),
+            total_driving_time_seconds=data.get("totalDrivingTimeSeconds", 0),
+            weights=data.get("weights"),
+        )
+
+
+

plansolve/professional_services/__init__.py

@@ -0,0 +1,28 @@
+"""Professional services optimization module."""
+
+from .api_client import ProfessionalServicesApiClient
+from .availability_time_span import AvailabilityTimeSpan
+from .contract import Contract
+from .models import (
+    Employee,
+    Task,
+    ProfessionalServicesRequest,
+    ScheduledEmployee,
+    ScheduledTask,
+    ProfessionalServicesResponse,
+    ProfessionalServicesResultResponse,
+)
+
+__all__ = [
+    "ProfessionalServicesApiClient",
+    "AvailabilityTimeSpan",
+    "Contract",
+    "Employee",
+    "Task",
+    "ProfessionalServicesRequest",
+    "ScheduledEmployee",
+    "ScheduledTask",
+    "ProfessionalServicesResponse",
+    "ProfessionalServicesResultResponse",
+]
+

plansolve/professional_services/api_client.py

@@ -0,0 +1,209 @@
+"""Professional services 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 (
+    ProfessionalServicesRequest,
+    ProfessionalServicesResponse,
+    ProfessionalServicesResultResponse,
+)
+
+
+class ProfessionalServicesApiClient:
+    """Client for professional services optimization API."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """
+        Initialize the professional services API client.
+
+        Args:
+            api_key: Optional API key for authenticated requests
+        """
+        self.base_url = f"https://plansolve.app{Routes.PROFESSIONAL_SERVICES_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[ProfessionalServicesRequest, Dict[str, Any]]
+    ) -> ProfessionalServicesResponse:
+        """
+        Start a new professional services optimization.
+
+        Args:
+            request: Professional services request (ProfessionalServicesRequest dataclass or dict)
+
+        Returns:
+            ProfessionalServicesResponse with jobId, solverJobId, result, and error
+
+        Raises:
+            requests.RequestException: If the API request fails
+        """
+        # Convert dataclass to dict if needed
+        if isinstance(request, ProfessionalServicesRequest):
+            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 ProfessionalServicesResponse.from_dict(response.json())
+
+    def get_result(self, job_id: str) -> ProfessionalServicesResultResponse:
+        """
+        Get the completed optimization result.
+
+        Args:
+            job_id: The job ID to get results for
+
+        Returns:
+            ProfessionalServicesResultResponse with employees and tasks
+
+        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 ProfessionalServicesResultResponse.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[ProfessionalServicesRequest, Dict[str, Any]],
+        poll_interval_ms: int = 5000,
+        max_attempts: int = 1000,
+    ) -> ProfessionalServicesResultResponse:
+        """
+        Start a job and wait for completion, polling for status.
+
+        Args:
+            request: Professional services request (ProfessionalServicesRequest dataclass or dict)
+            poll_interval_ms: Milliseconds to wait between status checks
+            max_attempts: Maximum number of polling attempts
+
+        Returns:
+            ProfessionalServicesResultResponse 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 = 1000,
+    ) -> ProfessionalServicesResultResponse:
+        """
+        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:
+            ProfessionalServicesResultResponse 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
+        """
+        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/professional_services/availability_time_span.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AvailabilityTimeSpan:
+    id: Optional[str] = None
+    start: Optional[str] = None
+    end: Optional[str] = None
+    type: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        result = {}
+        if self.id is not None:
+            result["id"] = self.id
+        if self.start is not None:
+            result["start"] = self.start
+        if self.end is not None:
+            result["end"] = self.end
+        if self.type is not None:
+            result["type"] = self.type
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AvailabilityTimeSpan":
+        return cls(
+            id=data.get("id"),
+            start=data.get("start"),
+            end=data.get("end"),
+            type=data.get("type"),
+        )