codex-services 0.1.0__py3-none-any.whl

codex_services/booking/_shared/exceptions.py

@@ -0,0 +1,318 @@
+"""
+codex_services.booking._shared.exceptions
+==========================================
+Custom exceptions for the booking engine.
+
+Hierarchy:
+    BookingEngineError (base)
+    ├── NoAvailabilityError      — no free slots for the request
+    ├── InvalidServiceDurationError — incorrect service duration
+    ├── InvalidBookingDateError  — incorrect/invalid date
+    ├── ResourceNotAvailableError — specific resource is not available
+    ├── SlotAlreadyBookedError   — race condition: slot was booked by another user
+    └── ChainBuildError          — chain was partially assembled but not completed
+
+Usage in the service layer:
+    from codex_services.booking._shared.exceptions import NoAvailabilityError
+
+    try:
+        result = finder.find(request, availability)
+        if not result.has_solutions:
+            raise NoAvailabilityError(
+                date=request.booking_date,
+                service_ids=[s.service_id for s in request.service_requests],
+            )
+    except NoAvailabilityError as e:
+        # Django view will catch and return a user-friendly message
+        return render(request, "booking/no_slots.html", {"error": str(e)})
+
+Imports:
+    from codex_services.booking._shared.exceptions import (
+        BookingEngineError,
+        NoAvailabilityError,
+        InvalidServiceDurationError,
+        InvalidBookingDateError,
+        ResourceNotAvailableError,
+    )
+"""
+
+from datetime import date
+
+
+class BookingEngineError(Exception):
+    """
+    Base exception of the booking engine.
+
+    All other exceptions inherit from it.
+    A Django view can catch BookingEngineError for unified handling
+    of all engine errors.
+
+    Example:
+        try:
+            result = service.book(...)
+        except BookingEngineError as e:
+            messages.error(request, str(e))
+            return redirect("booking:wizard")
+    """
+
+    default_message: str = "Booking system error"
+
+    def __init__(self, message: str | None = None) -> None:
+        super().__init__(message or self.default_message)
+
+
+class NoAvailabilityError(BookingEngineError):
+    """
+    The engine found no schedule options for the request.
+
+    Raised when ChainFinder.find() returns an empty EngineResult.
+    Translated to a user-friendly message in the Django view.
+
+    Attributes:
+        booking_date: Date searched for.
+        service_ids: List of service IDs from the request.
+
+    Example:
+        raise NoAvailabilityError(
+            booking_date=date(2024, 5, 10),
+            service_ids=["5", "12"],
+        )
+        # str(e) -> "No free slots on 10.05.2024 for the selected services."
+    """
+
+    default_message = "Unfortunately, there are no available slots for these services on the selected date."
+
+    def __init__(
+        self,
+        booking_date: date | None = None,
+        service_ids: list[str] | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.booking_date = booking_date
+        self.service_ids = service_ids or []
+
+        if message:
+            final_message = message
+        elif booking_date:
+            date_str = booking_date.strftime("%d.%m.%Y")
+            final_message = f"No free slots on {date_str} for the selected services. Please try choosing another date."
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)
+
+
+class InvalidServiceDurationError(BookingEngineError):
+    """
+    Incorrect service duration.
+
+    Raised if duration_minutes <= 0 or exceeds the explicit maximum.
+
+    Attributes:
+        service_id: ID of the problematic service.
+        duration_minutes: The passed duration value.
+
+    Example:
+        raise InvalidServiceDurationError(service_id="5", duration_minutes=0)
+        # str(e) -> "Service 5: incorrect duration 0 min."
+    """
+
+    default_message = "Incorrect service duration."
+
+    def __init__(
+        self,
+        service_id: str | None = None,
+        duration_minutes: int | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.service_id = service_id
+        self.duration_minutes = duration_minutes
+
+        if message:
+            final_message = message
+        elif service_id is not None and duration_minutes is not None:
+            final_message = (
+                f"Service {service_id}: incorrect duration {duration_minutes} min. Duration must be greater than 0."
+            )
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)
+
+
+class InvalidBookingDateError(BookingEngineError):
+    """
+    Booking date is invalid.
+
+    Example reasons:
+        - Date in the past
+        - Date beyond max_advance_days
+        - Salon is closed on this day
+
+    Attributes:
+        booking_date: Problematic date.
+        reason: Human-readable explanation.
+
+    Example:
+        raise InvalidBookingDateError(
+            booking_date=date(2020, 1, 1),
+            reason="Date in the past",
+        )
+    """
+
+    default_message = "The selected date is unavailable for booking."
+
+    def __init__(
+        self,
+        booking_date: date | None = None,
+        reason: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.booking_date = booking_date
+        self.reason = reason
+
+        if message:
+            final_message = message
+        elif booking_date and reason:
+            date_str = booking_date.strftime("%d.%m.%Y")
+            final_message = f"Date {date_str} is unavailable: {reason}."
+        elif booking_date:
+            date_str = booking_date.strftime("%d.%m.%Y")
+            final_message = f"Date {date_str} is unavailable for booking."
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)
+
+
+class SlotAlreadyBookedError(BookingEngineError):
+    """
+    Slot was free during display but became booked by the time of confirmation.
+
+    Race condition: client A and client B are viewing the same slot simultaneously.
+    A clicks "Book" first -> B receives this error.
+
+    Attributes:
+        resource_id: Resource ID.
+        service_id: Service ID.
+        booking_date: Booking date.
+        slot_time: Selected time (string "HH:MM").
+
+    Example:
+        raise SlotAlreadyBookedError(
+            resource_id="3",
+            service_id="5",
+            booking_date=date(2024, 5, 10),
+            slot_time="14:00",
+        )
+        # str(e) -> "Slot 14:00 on 10.05.2024 was booked. Please choose another time."
+    """
+
+    default_message = "The selected slot was booked. Please choose another time."
+
+    def __init__(
+        self,
+        resource_id: str | None = None,
+        service_id: str | None = None,
+        booking_date: date | None = None,
+        slot_time: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.resource_id = resource_id
+        self.service_id = service_id
+        self.booking_date = booking_date
+        self.slot_time = slot_time
+
+        if message:
+            final_message = message
+        elif slot_time and booking_date:
+            date_str = booking_date.strftime("%d.%m.%Y")
+            final_message = (
+                f"Slot {slot_time} on {date_str} was booked while you were processing. Please choose another time."
+            )
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)
+
+
+class ChainBuildError(BookingEngineError):
+    """
+    The engine could not assemble a chain for all services in the request.
+
+    Differs from NoAvailabilityError: here the chain was PARTIALLY assembled,
+    but not to the end (constraint violation, incompatible services, etc.).
+
+    Used when:
+        - max_chain_duration_minutes is exceeded
+        - Services are incompatible (future: excludes/tags)
+        - group_size > available parallel slots
+
+    Attributes:
+        failed_at_index: Index of the service (in service_requests) where assembly failed.
+        reason: Technical reason (for logs).
+
+    Example:
+        raise ChainBuildError(
+            failed_at_index=2,
+            reason="max_chain_duration_minutes=180 exceeded at service 'Coloring'",
+        )
+    """
+
+    default_message = "Could not find a schedule for all selected services."
+
+    def __init__(
+        self,
+        failed_at_index: int | None = None,
+        reason: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.failed_at_index = failed_at_index
+        self.reason = reason
+
+        if message:
+            final_message = message
+        elif reason:
+            final_message = f"Could not assemble the chain: {reason}."
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)
+
+
+class ResourceNotAvailableError(BookingEngineError):
+    """
+    Specific resource is not available for booking.
+
+    Used in RESOURCE_LOCKED mode when the selected resource
+    does not work on this day or their schedule is empty.
+
+    Attributes:
+        resource_id: Resource's ID.
+        booking_date: Date attempted to book.
+
+    Example:
+        raise ResourceNotAvailableError(resource_id="3", booking_date=date(2024,5,10))
+        # str(e) -> "Resource unavailable on 10.05.2024."
+    """
+
+    default_message = "The selected resource is unavailable on this date."
+
+    def __init__(
+        self,
+        resource_id: str | None = None,
+        booking_date: date | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.resource_id = resource_id
+        self.booking_date = booking_date
+
+        if message:
+            final_message = message
+        elif booking_date:
+            date_str = booking_date.strftime("%d.%m.%Y")
+            final_message = f"Resource unavailable on {date_str}. Please try another date."
+        else:
+            final_message = self.default_message
+
+        super().__init__(final_message)

codex_services/booking/_shared/interfaces.py

@@ -0,0 +1,66 @@
+"""
+codex_services.booking._shared.interfaces
+==========================================
+Protocol contracts for booking-specific adapters.
+Implement these protocols when building a new adapter for the booking engine.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, time
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from codex_services.booking._shared.dto import ResourceAvailability
+
+
+class ScheduleProvider(Protocol):
+    """Provides working schedules for resources."""
+
+    def get_working_hours(self, resource_id: str, target_date: date) -> tuple[time, time] | None:
+        """Return (start, end) of working day or None if day off."""
+        ...
+
+    def get_break_interval(self, resource_id: str, target_date: date) -> tuple[datetime, datetime] | None:
+        """Return (start, end) of break or None."""
+        ...
+
+
+class BusySlotsProvider(Protocol):
+    """Provides busy time slots for resources."""
+
+    def get_busy_intervals(
+        self, resource_ids: list[str], target_date: date
+    ) -> dict[str, list[tuple[datetime, datetime]]]:
+        """Return {resource_id: [(start, end), ...]} of busy times."""
+        ...
+
+
+class AvailabilityProvider(Protocol):
+    """
+    Full availability provider — the main adapter contract.
+    Implement this protocol for each framework adapter (Django, SQLAlchemy, etc.).
+    """
+
+    def build_resources_availability(
+        self,
+        resource_ids: list[str],
+        target_date: date,
+        cache_ttl: int = 300,
+        exclude_appointment_ids: list[int] | None = None,
+    ) -> dict[str, ResourceAvailability]:
+        """Build availability for a single date. Return {resource_id: ResourceAvailability}."""
+        ...
+
+    def build_availability_batch(
+        self,
+        resource_ids: list[str],
+        start_date: date,
+        end_date: date,
+    ) -> dict[date, dict[str, ResourceAvailability]]:
+        """
+        Build availability for a date range in a single batch.
+        Must avoid N+1 queries — group appointments in memory.
+        Return {date: {resource_id: ResourceAvailability}}.
+        """
+        ...

codex_services/booking/_shared/validators.py

@@ -0,0 +1,132 @@
+"""
+codex_services.booking._shared.validators
+==========================================
+Validators for ensuring booking data correctness.
+
+Used by ChainFinder to verify found solutions,
+and can also be used independently in tests or the service layer.
+
+Imports:
+    from codex_services.booking import BookingValidator
+"""
+
+from datetime import datetime
+
+from codex_services.booking._shared.dto import BookingSolution
+
+
+class BookingValidator:
+    """
+    A set of correctness checks for booking data.
+    Unaffected by the ORM — operates exclusively on DTOs.
+
+    Used by:
+        - ChainFinder: Ensuring found chains have no conflicts.
+        - Adapter: Final verification before creating Appointment instances in the DB.
+        - Tests: Isolated logic verification without Django.
+
+    Example:
+        v = BookingValidator()
+
+        # Check if a slot is free:
+        ok = v.is_slot_free(
+            slot_start=datetime(2024,5,10,10,0),
+            slot_end=datetime(2024,5,10,11,0),
+            busy_intervals=[(datetime(2024,5,10,9,0), datetime(2024,5,10,9,30))],
+        )
+        # → True (no overlap)
+
+        # Check entire chain for conflicts:
+        ok = v.no_conflicts(solutions)
+    """
+
+    def is_slot_free(
+        self,
+        slot_start: datetime,
+        slot_end: datetime,
+        busy_intervals: list[tuple[datetime, datetime]],
+    ) -> bool:
+        """
+        Verifies that the slot [slot_start, slot_end) does not overlap
+        with any of the busy intervals.
+
+        Uses a "half-open" interval — [start, end). If slot_end == busy_start,
+        it is NOT considered a conflict (adjacent slots are allowed).
+
+        Args:
+            slot_start: Start of the slot to check.
+            slot_end: End of the slot to check.
+            busy_intervals: List of busy intervals [(start, end), ...].
+
+        Returns:
+            True if the slot is free. False if there is an overlap.
+
+        Example:
+            # Busy 10:00-11:00. Requesting 10:30-11:30 → conflict:
+            is_slot_free(10:30, 11:30, [(10:00, 11:00)]) → False
+
+            # Requesting 11:00-12:00 → OK (adjacent slots):
+            is_slot_free(11:00, 12:00, [(10:00, 11:00)]) → True
+        """
+        return all(not (slot_start < busy_end and slot_end > busy_start) for busy_start, busy_end in busy_intervals)
+
+    def no_conflicts(
+        self,
+        solutions: list[BookingSolution],
+    ) -> bool:
+        """
+        Verifies that there are no resource conflicts within a set of solutions.
+        A resource cannot be occupied by two services simultaneously.
+
+        Groups solutions by resource_id and checks each group for overlaps.
+        Used by ChainFinder after assembling the chain for final verification.
+
+        Args:
+            solutions: List of BookingSolution objects (found slots).
+
+        Returns:
+            True if no conflicts exist. False if at least one resource is double-booked.
+
+        Example:
+            no_conflicts([
+                SingleServiceSolution(resource_id="1", start=9:00, gap_end=10:10),
+                SingleServiceSolution(resource_id="1", start=10:10, gap_end=11:10),
+            ])
+            # → True (slots are adjacent, no overlap)
+        """
+        by_resource: dict[str, list[BookingSolution]] = {}
+        for sol in solutions:
+            by_resource.setdefault(sol.resource_id, []).append(sol)
+
+        for _resource_id, resource_solutions in by_resource.items():
+            if len(resource_solutions) < 2:
+                continue
+            sorted_sols = sorted(resource_solutions, key=lambda s: s.start_time)
+            for i in range(len(sorted_sols) - 1):
+                current = sorted_sols[i]
+                next_sol = sorted_sols[i + 1]
+                # For solutions with gap_end_time, use it; otherwise use end_time
+                block_end = getattr(current, "gap_end_time", current.end_time)
+                if next_sol.start_time < block_end:
+                    return False
+
+        return True
+
+    def solution_fits_in_windows(
+        self,
+        solution: BookingSolution,
+        free_windows: list[tuple[datetime, datetime]],
+    ) -> bool:
+        """
+        Verifies that a solution's slot fits entirely inside one of the
+        resource's free windows.
+
+        Args:
+            solution: Found slot for a single service.
+            free_windows: Resource's free windows (from ResourceAvailability).
+
+        Returns:
+            True if the slot fits perfectly inside one of the given free windows.
+        """
+        block_end = getattr(solution, "gap_end_time", solution.end_time)
+        return any(solution.start_time >= w_start and block_end <= w_end for w_start, w_end in free_windows)

codex_services/booking/room/__init__.py

@@ -0,0 +1,7 @@
+"""codex_services.booking.room: Room booking (1 booking per day).
+
+TODO: Implement room booking type with:
+    - RoomBookingRequest (inherits BookingRequest)
+    - RoomAvailability (inherits ResourceAvailability)
+    - RoomBookingResult (inherits BookingResult)
+"""

codex_services/booking/slot_master/__init__.py

@@ -0,0 +1,58 @@
+"""Booking engine — chain service scheduling with backtracking."""
+
+from codex_services.booking._shared.exceptions import (
+    BookingEngineError,
+    ChainBuildError,
+    InvalidBookingDateError,
+    InvalidServiceDurationError,
+    NoAvailabilityError,
+    ResourceNotAvailableError,
+    SlotAlreadyBookedError,
+)
+from codex_services.booking._shared.interfaces import AvailabilityProvider, BusySlotsProvider, ScheduleProvider
+
+from .api import find_nearest_slots, find_slots
+from .chain_finder import ChainFinder
+from .dto import (
+    BookingChainSolution,
+    BookingEngineRequest,
+    EngineResult,
+    MasterAvailability,
+    ServiceRequest,
+    SingleServiceSolution,
+    WaitlistEntry,
+)
+from .modes import BookingMode
+from .scorer import BookingScorer, ScoringWeights
+
+__all__ = [
+    # High-level facade (dict-based API)
+    "find_slots",
+    "find_nearest_slots",
+    # Engine
+    "ChainFinder",
+    "BookingScorer",
+    "ScoringWeights",
+    # Interfaces
+    "AvailabilityProvider",
+    "BusySlotsProvider",
+    "ScheduleProvider",
+    # Request / availability DTOs
+    "BookingEngineRequest",
+    "ServiceRequest",
+    "MasterAvailability",
+    "BookingMode",
+    # Result DTOs
+    "EngineResult",
+    "BookingChainSolution",
+    "SingleServiceSolution",
+    "WaitlistEntry",
+    # Exceptions
+    "BookingEngineError",
+    "NoAvailabilityError",
+    "InvalidServiceDurationError",
+    "InvalidBookingDateError",
+    "ResourceNotAvailableError",
+    "SlotAlreadyBookedError",
+    "ChainBuildError",
+]