Skip to content

Model version

openai_model_registry.model_version

Model version handling for OpenAI models.

This module provides utilities for parsing and comparing model versions in the format YYYY-MM-DD.

Classes

ModelVersion

Represents a model version in YYYY-MM-DD format.

This class handles parsing, validation, and comparison of model version dates.

Attributes:

Name Type Description
year

The year component of the version
month

The month component of the version
day

The day component of the version
Source code in src/openai_model_registry/model_version.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
class ModelVersion:
    """Represents a model version in YYYY-MM-DD format.

    This class handles parsing, validation, and comparison of model version dates.

    Attributes:
        year: The year component of the version
        month: The month component of the version
        day: The day component of the version
    """

    def __init__(self, year: int, month: int, day: int) -> None:
        """Initialize a model version.

        Args:
            year: The year component (e.g., 2024)
            month: The month component (1-12)
            day: The day component (1-31)
        """
        self.year = year
        self.month = month
        self.day = day

    def __eq__(self, other: object) -> bool:
        """Check if two versions are equal.

        Args:
            other: The other version to compare with

        Returns:
            bool: True if versions are equal, False otherwise
        """
        if not isinstance(other, ModelVersion):
            return NotImplemented
        return self.year == other.year and self.month == other.month and self.day == other.day

    def __lt__(self, other: "ModelVersion") -> bool:
        """Check if this version is earlier than another.

        Args:
            other: The other version to compare with

        Returns:
            bool: True if this version is earlier, False otherwise
        """
        if self.year != other.year:
            return self.year < other.year
        if self.month != other.month:
            return self.month < other.month
        return self.day < other.day

    def __le__(self, other: "ModelVersion") -> bool:
        """Check if this version is earlier than or equal to another.

        Args:
            other: The other version to compare with

        Returns:
            bool: True if this version is earlier or equal, False otherwise
        """
        return self < other or self == other

    def __gt__(self, other: "ModelVersion") -> bool:
        """Check if this version is later than another.

        Args:
            other: The other version to compare with

        Returns:
            bool: True if this version is later, False otherwise
        """
        return not (self <= other)

    def __ge__(self, other: "ModelVersion") -> bool:
        """Check if this version is later than or equal to another.

        Args:
            other: The other version to compare with

        Returns:
            bool: True if this version is later or equal, False otherwise
        """
        return not (self < other)

    def __repr__(self) -> str:
        """Get string representation of the version.

        Returns:
            str: Version in YYYY-MM-DD format
        """
        return f"{self.year:04d}-{self.month:02d}-{self.day:02d}"

    @classmethod
    def from_string(cls, version_str: str) -> "ModelVersion":
        """Create a version from a string in YYYY-MM-DD format.

        Args:
            version_str: The version string to parse

        Returns:
            A new ModelVersion instance

        Raises:
            InvalidDateError: If the string is not a valid version
        """
        # Strip whitespace and validate input
        version_str = version_str.strip()
        if not version_str:
            raise InvalidDateError("Version string cannot be empty")

        # Check for reasonable string length (prevent excessive input)
        if len(version_str) > 50:
            raise InvalidDateError(f"Version string too long: {len(version_str)} characters. Maximum allowed: 50")

        parts = version_str.split("-")
        if len(parts) != 3:
            raise InvalidDateError(f"Invalid version format: {version_str}. " f"Expected YYYY-MM-DD.")

        try:
            year = int(parts[0])
            month = int(parts[1])
            day = int(parts[2])
        except ValueError:
            raise InvalidDateError(
                f"Invalid version components in {version_str}. " f"Year, month, and day must be integers."
            )

        # Basic validation
        if not (1000 <= year <= 9999):
            raise InvalidDateError(f"Invalid year: {year}. Must be 1000-9999.")
        if not (1 <= month <= 12):
            raise InvalidDateError(f"Invalid month: {month}. Must be 1-12.")
        if not (1 <= day <= 31):
            raise InvalidDateError(f"Invalid day: {day}. Must be 1-31.")

        # Calendar validation
        try:
            date(year, month, day)
        except ValueError as e:
            raise InvalidDateError(f"Invalid date: {version_str}. {str(e)}")

        return cls(year, month, day)

    @staticmethod
    def parse_from_model(model: str) -> Tuple[str, "ModelVersion"]:
        """Parse a model name into base name and version.

        Args:
            model: Full model name with version (e.g., "gpt-4o-2024-08-06")

        Returns:
            Tuple of (base_name, version)
            Example: ("gpt-4o", ModelVersion(2024, 8, 6))

        Raises:
            ModelFormatError: If the model name does not follow the expected format
            InvalidDateError: If the date part of the model name is invalid
        """
        # Format: "{base_model}-{YYYY}-{MM}-{DD}"
        pattern = re.compile(r"^([\w-]+?)-(\d{4}-\d{2}-\d{2})$")
        match = pattern.match(model)

        if not match:
            raise ModelFormatError(
                f"Invalid model format: {model}. Expected format: " f"base-name-YYYY-MM-DD (e.g., gpt-4o-2024-08-06)",
                model=model,
            )

        base_model = match.group(1)
        version_str = match.group(2)

        try:
            version = ModelVersion.from_string(version_str)
            return base_model, version
        except InvalidDateError as e:
            raise ModelFormatError(
                f"Invalid version in model name {model}: {e}",
                model=model,
            ) from e

    @staticmethod
    def is_dated_model(model_name: str) -> bool:
        """Check if a model name follows the dated model format.

        Args:
            model_name: The model name to check

        Returns:
            True if the model name follows the dated format (with YYYY-MM-DD suffix)
        """
        return bool(re.match(r"^.*-\d{4}-\d{2}-\d{2}$", model_name))
Functions
__eq__(other)

Check if two versions are equal.

Parameters:

Name Type Description Default
other object

The other version to compare with

 required

Returns:

Name Type Description
bool bool

True if versions are equal, False otherwise
Source code in src/openai_model_registry/model_version.py 
37
38
39
40
41
42
43
44
45
46
47
48
def __eq__(self, other: object) -> bool:
    """Check if two versions are equal.

    Args:
        other: The other version to compare with

    Returns:
        bool: True if versions are equal, False otherwise
    """
    if not isinstance(other, ModelVersion):
        return NotImplemented
    return self.year == other.year and self.month == other.month and self.day == other.day
__ge__(other)

Check if this version is later than or equal to another.

Parameters:

Name Type Description Default
other ModelVersion

The other version to compare with

 required

Returns:

Name Type Description
bool bool

True if this version is later or equal, False otherwise
Source code in src/openai_model_registry/model_version.py 
87
88
89
90
91
92
93
94
95
96
def __ge__(self, other: "ModelVersion") -> bool:
    """Check if this version is later than or equal to another.

    Args:
        other: The other version to compare with

    Returns:
        bool: True if this version is later or equal, False otherwise
    """
    return not (self < other)
__gt__(other)

Check if this version is later than another.

Parameters:

Name Type Description Default
other ModelVersion

The other version to compare with

 required

Returns:

Name Type Description
bool bool

True if this version is later, False otherwise
Source code in src/openai_model_registry/model_version.py 
76
77
78
79
80
81
82
83
84
85
def __gt__(self, other: "ModelVersion") -> bool:
    """Check if this version is later than another.

    Args:
        other: The other version to compare with

    Returns:
        bool: True if this version is later, False otherwise
    """
    return not (self <= other)
__init__(year, month, day)

Initialize a model version.

Parameters:

Name Type Description Default
year int

The year component (e.g., 2024)

 required
month int

The month component (1-12)

 required
day int

The day component (1-31)

 required
Source code in src/openai_model_registry/model_version.py 
25
26
27
28
29
30
31
32
33
34
35
def __init__(self, year: int, month: int, day: int) -> None:
    """Initialize a model version.

    Args:
        year: The year component (e.g., 2024)
        month: The month component (1-12)
        day: The day component (1-31)
    """
    self.year = year
    self.month = month
    self.day = day
__le__(other)

Check if this version is earlier than or equal to another.

Parameters:

Name Type Description Default
other ModelVersion

The other version to compare with

 required

Returns:

Name Type Description
bool bool

True if this version is earlier or equal, False otherwise
Source code in src/openai_model_registry/model_version.py 
65
66
67
68
69
70
71
72
73
74
def __le__(self, other: "ModelVersion") -> bool:
    """Check if this version is earlier than or equal to another.

    Args:
        other: The other version to compare with

    Returns:
        bool: True if this version is earlier or equal, False otherwise
    """
    return self < other or self == other
__lt__(other)

Check if this version is earlier than another.

Parameters:

Name Type Description Default
other ModelVersion

The other version to compare with

 required

Returns:

Name Type Description
bool bool

True if this version is earlier, False otherwise
Source code in src/openai_model_registry/model_version.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def __lt__(self, other: "ModelVersion") -> bool:
    """Check if this version is earlier than another.

    Args:
        other: The other version to compare with

    Returns:
        bool: True if this version is earlier, False otherwise
    """
    if self.year != other.year:
        return self.year < other.year
    if self.month != other.month:
        return self.month < other.month
    return self.day < other.day
__repr__()

Get string representation of the version.

Returns:

Name Type Description
str str

Version in YYYY-MM-DD format
Source code in src/openai_model_registry/model_version.py 
 98
 99
100
101
102
103
104
def __repr__(self) -> str:
    """Get string representation of the version.

    Returns:
        str: Version in YYYY-MM-DD format
    """
    return f"{self.year:04d}-{self.month:02d}-{self.day:02d}"
from_string(version_str) classmethod

Create a version from a string in YYYY-MM-DD format.

Parameters:

Name Type Description Default
version_str str

The version string to parse

 required

Returns:

Type Description
ModelVersion

A new ModelVersion instance

Raises:

Type Description
InvalidDateError

If the string is not a valid version
Source code in src/openai_model_registry/model_version.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
@classmethod
def from_string(cls, version_str: str) -> "ModelVersion":
    """Create a version from a string in YYYY-MM-DD format.

    Args:
        version_str: The version string to parse

    Returns:
        A new ModelVersion instance

    Raises:
        InvalidDateError: If the string is not a valid version
    """
    # Strip whitespace and validate input
    version_str = version_str.strip()
    if not version_str:
        raise InvalidDateError("Version string cannot be empty")

    # Check for reasonable string length (prevent excessive input)
    if len(version_str) > 50:
        raise InvalidDateError(f"Version string too long: {len(version_str)} characters. Maximum allowed: 50")

    parts = version_str.split("-")
    if len(parts) != 3:
        raise InvalidDateError(f"Invalid version format: {version_str}. " f"Expected YYYY-MM-DD.")

    try:
        year = int(parts[0])
        month = int(parts[1])
        day = int(parts[2])
    except ValueError:
        raise InvalidDateError(
            f"Invalid version components in {version_str}. " f"Year, month, and day must be integers."
        )

    # Basic validation
    if not (1000 <= year <= 9999):
        raise InvalidDateError(f"Invalid year: {year}. Must be 1000-9999.")
    if not (1 <= month <= 12):
        raise InvalidDateError(f"Invalid month: {month}. Must be 1-12.")
    if not (1 <= day <= 31):
        raise InvalidDateError(f"Invalid day: {day}. Must be 1-31.")

    # Calendar validation
    try:
        date(year, month, day)
    except ValueError as e:
        raise InvalidDateError(f"Invalid date: {version_str}. {str(e)}")

    return cls(year, month, day)
is_dated_model(model_name) staticmethod

Check if a model name follows the dated model format.

Parameters:

Name Type Description Default
model_name str

The model name to check

 required

Returns:

Type Description
bool

True if the model name follows the dated format (with YYYY-MM-DD suffix)
Source code in src/openai_model_registry/model_version.py 
194
195
196
197
198
199
200
201
202
203
204
@staticmethod
def is_dated_model(model_name: str) -> bool:
    """Check if a model name follows the dated model format.

    Args:
        model_name: The model name to check

    Returns:
        True if the model name follows the dated format (with YYYY-MM-DD suffix)
    """
    return bool(re.match(r"^.*-\d{4}-\d{2}-\d{2}$", model_name))
parse_from_model(model) staticmethod

Parse a model name into base name and version.

Parameters:

Name Type Description Default
model str

Full model name with version (e.g., "gpt-4o-2024-08-06")

 required

Returns:

Name Type Description
str

Tuple of (base_name, version)
Example ModelVersion

("gpt-4o", ModelVersion(2024, 8, 6))

Raises:

Type Description
ModelFormatError

If the model name does not follow the expected format
InvalidDateError

If the date part of the model name is invalid
Source code in src/openai_model_registry/model_version.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
@staticmethod
def parse_from_model(model: str) -> Tuple[str, "ModelVersion"]:
    """Parse a model name into base name and version.

    Args:
        model: Full model name with version (e.g., "gpt-4o-2024-08-06")

    Returns:
        Tuple of (base_name, version)
        Example: ("gpt-4o", ModelVersion(2024, 8, 6))

    Raises:
        ModelFormatError: If the model name does not follow the expected format
        InvalidDateError: If the date part of the model name is invalid
    """
    # Format: "{base_model}-{YYYY}-{MM}-{DD}"
    pattern = re.compile(r"^([\w-]+?)-(\d{4}-\d{2}-\d{2})$")
    match = pattern.match(model)

    if not match:
        raise ModelFormatError(
            f"Invalid model format: {model}. Expected format: " f"base-name-YYYY-MM-DD (e.g., gpt-4o-2024-08-06)",
            model=model,
        )

    base_model = match.group(1)
    version_str = match.group(2)

    try:
        version = ModelVersion.from_string(version_str)
        return base_model, version
    except InvalidDateError as e:
        raise ModelFormatError(
            f"Invalid version in model name {model}: {e}",
            model=model,
        ) from e