Serko Northsky TTV Scoring

The TTV (Trip Travel Value) Scoring system is Serko Northsky's intelligent ranking engine that evaluates trip options (accommodations, flights) against user preferences and company policies to provide personalized rankings.

Overview

The TTV Scoring system works in four steps:

1. Extracting features from trip option entities (e.g., price, distance, amenities)
2. Evaluating features against user preferences and company policies
3. Computing scores that determine option rankings
4. Generating insights that explain why options scored well or poorly

Architecture

Class Hierarchy

ScoringCriterion (abstract base for evaluation criteria)
    │
    ├── Preference (user/trip preferences)
    │       ├── AccommodationPreferences/ (17 implementations)
    │       └── FlightPreferences/ (5 implementations)
    │
    └── Policy (company compliance rules)
            └── PolicyModels (stay rules, flight rules)

OptionFeature[T, TripOptionPart] (abstract base for extractable features)
    │
    ├── AccommodationFeature[T] → extracts from Accommodation entity
    ├── ProductFeature[T] → extracts from Product entity
    ├── RoomFeature[T] → extracts from Room entity
    └── FlightFeature[T] → extracts from Flight entity

Component Flow

                    ┌───────────────────┐
                    │ ScoringCriterion  │
                    │ (defines how to   │
                    │  evaluate)        │
                    └────────┬──────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
    ┌─────────▼─────────┐       ┌───────────▼───────────┐
    │    Preference     │       │        Policy         │
    │ (user choices)    │       │ (company rules)       │
    └───────────────────┘       └───────────────────────┘
              │                             │
              │    ┌──────────────────┐     │
              └───►│  OptionFeature   │◄────┘
                   │ (extracts values │
                   │  to be scored)   │
                   └────────┬─────────┘
                            │
                            ▼
                   ┌──────────────────┐
                   │   compute_score  │
                   │ (returns weighted│
                   │  score 0.0-1.0)  │
                   └──────────────────┘

ScoringCriterion Base Class

The ScoringCriterion is the abstract base class for all scoring criteria.

Key class attributes:

• name, description — Human-readable identifiers
• main_condition_field, main_condition_value_type — Condition configuration
• condition_operator — Comparison operator (IS_EQUAL, IS_LESS_THAN, etc.)
• trip_step_type — ACCOMMODATION or FLIGHT
• weight — Score multiplier (-100 to 100)

Condition Operators

Operator	Description	Example
IS_EQUAL	Exact match	Brand equals "Hilton"
IS_NOT_EQUAL	Not equal	Exclude specific value
IS_GREATER_THAN	Greater than	Rating greater than 3.5
IS_GREATER_THAN_OR_EQUAL	Greater or equal	Room size at least 20
IS_LESS_THAN	Less than	Price under 200
IS_LESS_THAN_OR_EQUAL	Less or equal	Distance at most 5
CONTAINS	Value in collection	Amenity contains keyword

OptionFeature Base Class

The OptionFeature is a generic base class for extractable features:

Type parameters:

• T — Value type (float, bool, str, int, datetime)
• TripOptionPart — Source entity (Accommodation, Flight, etc.)

Key methods:

• create() — Factory method to extract feature from entity
• to_insight() — Generate natural language description

Accommodation Implementation

See option_feature/accommodation/ and preference/accommodation_preferences/ for implementations.

Features

Feature	Type	Category	Description
DistanceFeature	float	Location	Distance from search center (km)
StarRatingFeature	float	Quality	Star rating (1-5)
GuestRatingFeature	float	Quality	Guest review rating
ChainFeature	str	Brand	Hotel chain name
HasGymFeature	bool	Amenities	Has gym/fitness
HasWifiFeature	bool	Amenities	Has WiFi
HasBreakfastFeature	bool	Amenities	Offers breakfast
PricePerNightFeature	float	Pricing	Nightly rate
IsRefundableFeature	bool	Policies	Is refundable

Preferences

Preference	Type	Operator	Category
MaximumPricePerNightPreference	float	IS_LESS_THAN	Budget
MinimumStarRatingPreference	float	IS_GREATER_THAN	Quality
MaximumDistancePreference	float	IS_LESS_THAN	Location
AccommodationBrandPreference	str	IS_EQUAL	Brand
HasGymPreference	bool	IS_EQUAL	Amenities
RoomIsRefundablePreference	bool	IS_EQUAL	Policies

Flight Implementation

See option_feature/flight/ and preference/flight_preferences/ for implementations.

Features

Feature	Type	Category	Description
TotalPriceFeature	float	Pricing	Total flight price
NumberOfLegsFeature	int	Route	Number of segments
ValidatingCarrierFeature	str	Airline	Ticketing airline
TotalDurationFeature	int	Schedule	Duration in minutes
TotalEmissionsFeature	float	Environmental	CO2 emissions (kg)
CabinClassFeature	list[CabinType]	Comfort	Cabin per leg
DepartureTimeFeature	datetime	Schedule	First leg departure

Preferences

Preference	Type	Operator
AirlinePreference	str	IS_EQUAL
MaximumFlightPricePreference	float	IS_LESS_THAN
MaximumNumberOfLegsPreference	int	IS_LESS_THAN_OR_EQUAL
CabinClassPreference	str	IS_EQUAL
FlightIsRefundablePreference	bool	IS_EQUAL

Registry System

Features and preferences are automatically registered using metaclasses. See PreferenceRegistry and PreferenceFactory.

Source Files Reference

Purpose	Path
ScoringCriterion	models/core_models/scoring/scoring_criterion.py
OptionFeature	models/core_models/scoring/option_feature/option_feature.py
Preference	models/core_models/scoring/preference/preference.py
PreferenceFactory	models/core_models/scoring/preference/preference_factory.py
AccommodationFeatures	models/core_models/scoring/option_feature/accommodation/
FlightFeatures	models/core_models/scoring/option_feature/flight/