Skip to content

Model Reference API

ModelReference is the parsed form of the opaque user-facing --model input.

Normalized representation of a user-supplied model reference string.

Source code in src/ollm/runtime/reference.py 
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
@dataclass(frozen=True, slots=True)
class ModelReference:
    """Normalized representation of a user-supplied model reference string."""

    raw: str
    scheme: str | None
    identifier: str
    revision: str | None
    local_path: Path | None

    @classmethod
    def parse(cls, raw_reference: str) -> Self:
        """Parse a raw model reference into a structured form."""
        raw = raw_reference.strip()
        if not raw:
            raise ValueError("Model reference cannot be empty")

        scheme, value = _split_reference(raw)
        if scheme == "path":
            path = Path(value).expanduser().resolve()
            return cls(
                raw=raw,
                scheme=scheme,
                identifier=str(path),
                revision=None,
                local_path=path,
            )

        if scheme is None and _looks_like_local_path(raw):
            path = Path(raw).expanduser().resolve()
            return cls(
                raw=raw,
                scheme=None,
                identifier=str(path),
                revision=None,
                local_path=path,
            )

        identifier, revision = _split_revision(value)
        return cls(
            raw=raw,
            scheme=scheme,
            identifier=identifier,
            revision=revision,
            local_path=None,
        )

    def is_huggingface_reference(self) -> bool:
        """Return whether the reference should be treated as a Hugging Face repo ID."""
        if self.scheme == "hf":
            return True
        if self.scheme is not None:
            return False
        if "/" not in self.identifier:
            return False
        return " " not in self.identifier

    def materialization_name(self) -> str:
        """Return the directory name used for local materialization of this reference."""
        base = self.identifier.replace("/", "--").replace(":", "--")
        if self.revision is None:
            return base
        revision = self.revision.replace("/", "--").replace(":", "--")
        return f"{base}--{revision}"

parse classmethod 

parse(raw_reference: str) -> Self

Parse a raw model reference into a structured form.

Source code in src/ollm/runtime/reference.py 
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
@classmethod
def parse(cls, raw_reference: str) -> Self:
    """Parse a raw model reference into a structured form."""
    raw = raw_reference.strip()
    if not raw:
        raise ValueError("Model reference cannot be empty")

    scheme, value = _split_reference(raw)
    if scheme == "path":
        path = Path(value).expanduser().resolve()
        return cls(
            raw=raw,
            scheme=scheme,
            identifier=str(path),
            revision=None,
            local_path=path,
        )

    if scheme is None and _looks_like_local_path(raw):
        path = Path(raw).expanduser().resolve()
        return cls(
            raw=raw,
            scheme=None,
            identifier=str(path),
            revision=None,
            local_path=path,
        )

    identifier, revision = _split_revision(value)
    return cls(
        raw=raw,
        scheme=scheme,
        identifier=identifier,
        revision=revision,
        local_path=None,
    )

is_huggingface_reference 

is_huggingface_reference() -> bool

Return whether the reference should be treated as a Hugging Face repo ID.

Source code in src/ollm/runtime/reference.py 
62
63
64
65
66
67
68
69
70
def is_huggingface_reference(self) -> bool:
    """Return whether the reference should be treated as a Hugging Face repo ID."""
    if self.scheme == "hf":
        return True
    if self.scheme is not None:
        return False
    if "/" not in self.identifier:
        return False
    return " " not in self.identifier

materialization_name 

materialization_name() -> str

Return the directory name used for local materialization of this reference.

Source code in src/ollm/runtime/reference.py 
72
73
74
75
76
77
78
def materialization_name(self) -> str:
    """Return the directory name used for local materialization of this reference."""
    base = self.identifier.replace("/", "--").replace(":", "--")
    if self.revision is None:
        return base
    revision = self.revision.replace("/", "--").replace(":", "--")
    return f"{base}--{revision}"