model

Documentation

Index

• Constants
• Variables
• func IsValidNamePart(kind PartKind, s string) bool
• type Digest
  • func MustParseDigest(s string) Digest
  • func ParseDigest(s string) Digest
  • func (d Digest) IsValid() bool
  • func (d Digest) LogValue() slog.Value
  • func (d Digest) Split() (typ, digest string)
  • func (d Digest) String() string
• type Name
  • func MustParseName(s, fill string) Name
  • func ParseName(s string) Name
  • func ParseNameFill(s, fill string) Name
  • func ParseNameFromFilepath(s, fill string) Name
  • func ParseNameFromURLPath(s, fill string) Name
  • func ParseNameFromURLPathFill(s, fill string) Name
  • func (r Name) Build() string
  • func (r Name) CompareFold(o Name) int
  • func (r Name) Digest() Digest
  • func (r Name) DisplayLong() string
  • func (r Name) DisplayLongest() string
  • func (r Name) DisplayShortest(mask string) string
  • func (r Name) DisplayURLPath() string
  • func (r Name) EqualFold(o Name) bool
  • func (r Name) Filepath() string
  • func (r Name) FilepathNoBuild() string
  • func (r Name) GoString() string
  • func (r Name) Host() string
  • func (r Name) IsComplete() bool
  • func (r Name) IsCompleteNoBuild() bool
  • func (r Name) IsResolved() bool
  • func (r Name) IsValid() bool
  • func (r Name) IsZero() bool
  • func (r Name) LogValue() slog.Value
  • func (r Name) MapHash() uint64
  • func (r Name) Model() string
  • func (r Name) Namespace() string
  • func (r Name) Tag() string
  • func (r Name) URLPath() string
  • func (r Name) WithBuild(build string) Name
  • func (r Name) WithDigest(digest Digest) Name
• type PartKind
  • func (k PartKind) String() string

Examples

• Name (CompleteAndResolved)
• Name.CompareFold (Sort)
• Name.DisplayShortest
• Name.MapHash

Constants

const (
	// MaskDefault is the default mask used by [Name.DisplayShortest].
	MaskDefault = "registry.ollama.ai/library/?:latest"

	// MaskNothing is a mask that masks nothing.
	MaskNothing = "?/?/?:?"

	// DefaultFill is the default fill used by [ParseName].
	FillDefault = "registry.ollama.ai/library/?:latest+Q4_0"

	// FillNothing is a fill that fills nothing.
	FillNothing = "?/?/?:?+?"
)

Defaults

const MaxNamePartLen = 128

Variables

var (
	// ErrInvalidName, ErrIncompleteName, and ErrInvalidDigest are not
	// used by this package, but are exported so that other packages can
	// use them, instead of defining their own errors for them.
	ErrInvalidName    = errors.New("invalid model name")
	ErrIncompleteName = errors.New("incomplete model name")
	ErrInvalidDigest  = errors.New("invalid digest")
)

Errors

Functions

func IsValidNamePart

func IsValidNamePart(kind PartKind, s string) bool

IsValidNamePart reports if s contains all valid characters for the given part kind and is under MaxNamePartLen bytes.

Types

type Digest

type Digest struct {
	// contains filtered or unexported fields
}

Digest represents a digest of a model Manifest. It is a comparable value type and is immutable.

The zero Digest is not a valid digest.

func MustParseDigest

func MustParseDigest(s string) Digest

func ParseDigest

func ParseDigest(s string) Digest

ParseDigest parses a string in the form of "<digest-type>-<digest>" into a Digest.

func (Digest) IsValid

func (d Digest) IsValid() bool

IsValid returns true if the digest is valid (not zero).

A valid digest may be created only by ParseDigest, or ParseName(name).Digest().

func (Digest) LogValue

func (d Digest) LogValue() slog.Value

LogValue implements slog.Value.

func (Digest) Split

func (d Digest) Split() (typ, digest string)

Split returns the digest type and the digest value.

func (Digest) String

func (d Digest) String() string

String returns the digest in the form of "<digest-type>-<digest>", or the empty string if the digest is invalid.

type Name

type Name struct {
	// contains filtered or unexported fields
}

Name is an opaque reference to a model. It holds the parts of a model with the case preserved, but is not directly comparable with other Names since model names can be represented with different casing depending on the use case. For instance, "Mistral" and "mistral" are the same model but each version may have come from different sources (e.g. copied from a Web page, or from a file path).

Valid Names can ONLY be constructed by calling ParseName.

A Name is valid if and only if is have a valid Model part. The other parts are optional.

A Name is considered "complete" if it has all parts present. To check if a Name is complete, use Name.IsComplete.

To compare two names in a case-insensitive manner, use Name.EqualFold.

The parts of a Name are:

• Host: the domain of the model (optional)
• Namespace: the namespace of the model (optional)
• Model: the name of the model (required)
• Tag: the tag of the model (optional)
• Build: the build of the model; usually the quantization or "file type" (optional)

The parts can be obtained in their original form by calling [Name.Parts].

To check if a Name has at minimum a valid model part, use Name.IsValid.

Example (CompleteAndResolved)

for _, s := range []string{
	"x/y/z:latest+q4_0@sha123-abc",
	"x/y/z:latest+q4_0",
	"@sha123-abc",
} {
	name := ParseNameFill(s, FillNothing)
	fmt.Printf("complete:%v resolved:%v  digest:%s\n", name.IsComplete(), name.IsResolved(), name.Digest())
}

Output:

complete:true resolved:true  digest:sha123-abc
complete:true resolved:false  digest:
complete:false resolved:true  digest:sha123-abc

func MustParseName

func MustParseName(s, fill string) Name

func ParseName

func ParseName(s string) Name

ParseName parses s into a Name, and returns the result of filling it with FillDefault. The input string must be a valid string representation of a model

func ParseNameFill

func ParseNameFill(s, fill string) Name

ParseName parses s into a Name, and returns the result of filling it with defaults. The input string must be a valid string representation of a model name in the form:

[host/][namespace/]<model>[:tag][+build][@<digest-type>-<digest>]

The name part is required, all others are optional. If a part is missing, it is left empty in the returned Name. If a part is invalid, the zero Ref value is returned.

The build part is normalized to uppercase.

Examples of valid paths:

"example.com/library/mistral:7b+x"
"example.com/eva/mistral:7b+Q4_0"
"mistral:7b+x"
"example.com/mike/mistral:latest+Q4_0"
"example.com/bruce/mistral:latest"
"example.com/pdevine/thisisfine:7b+Q4_0@sha256-1234567890abcdef"

Examples of invalid paths:

"example.com/mistral:7b+"
"example.com/mistral:7b+Q4_0+"
"x/y/z/z:8n+I"
""

It returns the zero value if any part is invalid.

Fills

For any valid s, the fill string is used to fill in missing parts of the Name. The fill string must be a valid Name with the exception that any part may be the string ("?"), which will not be considered for filling.

func ParseNameFromFilepath

func ParseNameFromFilepath(s, fill string) Name

ParseNameFromFilepath parses a file path into a Name. The input string must be a valid file path representation of a model name in the form:

host/namespace/model/tag/build

The zero valid is returned if s does not contain all path elements leading up to the model part, or if any path element is an invalid part for the its corresponding part kind.

The fill string is used to fill in missing parts of any constructed Name. See ParseName for more information on the fill string.

func ParseNameFromURLPath

func ParseNameFromURLPath(s, fill string) Name

ParseNameFromURLPath parses forms of a URL path into a Name. Specifically, it trims any leading "/" and then calls ParseName with fill.

func ParseNameFromURLPathFill

func ParseNameFromURLPathFill(s, fill string) Name

func (Name) Build

func (r Name) Build() string

func (Name) CompareFold

func (r Name) CompareFold(o Name) int

CompareFold performs a case-insensitive cmp.Compare on r and o.

This can be used with slices.SortFunc.

For simple equality checks, use Name.EqualFold.

Example (Sort)

names := []Name{
	ParseNameFill("mistral:latest", FillNothing),
	ParseNameFill("mistRal:7b+q4", FillNothing),
	ParseNameFill("MIstral:7b", FillNothing),
}

slices.SortFunc(names, Name.CompareFold)

for _, n := range names {
	fmt.Println(n.DisplayLong())
}

Output:

MIstral:7b
mistRal:7b+q4
mistral:latest

func (Name) Digest

func (r Name) Digest() Digest

Digest returns the digest part of the Name, if any.

If Digest returns a non-empty string, then Name.IsResolved will return true, and digest is considered valid.

func (Name) DisplayLong

func (r Name) DisplayLong() string

DisplayLong returns the fullest possible display string in form:

<host>/<namespace>/<model>:<tag>+<build>

If any part is missing, it is omitted from the display string.

func (Name) DisplayLongest

func (r Name) DisplayLongest() string

DisplayLongest returns the result of r.DisplayShortest(MaskNothing).

func (Name) DisplayShortest

func (r Name) DisplayShortest(mask string) string

DisplayShortest returns the shortest possible, masked display string in form:

[host/][<namespace>/]<model>[:<tag>]

Masks

The mask is a string that specifies which parts of the name to omit based on case-insensitive comparison. Name.DisplayShortest omits parts of the name that are the same as the mask, moving from left to right until the first unequal part is found. It then moves right to left until the first unequal part is found. The result is the shortest possible display string.

Unlike a Name the mask can contain "?" characters which are treated as wildcards. A "?" will never match a part of the name, since a valid name can never contain a "?" character.

For example: Given a Name ("registry.ollama.ai/library/mistral:latest") masked with ("registry.ollama.ai/library/?:latest") will produce the display string ("mistral").

If mask is the empty string, then MaskDefault is used.

DisplayShortest panics if the mask is not the empty string, MaskNothing, and invalid.

Builds

For now, DisplayShortest does consider the build or return one in the result. We can lift this restriction when needed.

Example

name := ParseNameFill("example.com/jmorganca/mistral:latest+Q4_0", FillNothing)

fmt.Println(name.DisplayShortest("example.com/jmorganca/_:latest"))
fmt.Println(name.DisplayShortest("example.com/_/_:latest"))
fmt.Println(name.DisplayShortest("example.com/_/_:_"))
fmt.Println(name.DisplayShortest("_/_/_:_"))

// Default
name = ParseNameFill("registry.ollama.ai/library/mistral:latest+Q4_0", FillNothing)
fmt.Println(name.DisplayShortest(""))

Output:

mistral
jmorganca/mistral
jmorganca/mistral:latest
example.com/jmorganca/mistral:latest
mistral

func (Name) DisplayURLPath

func (r Name) DisplayURLPath() string

URLPath returns a complete, canonicalized, relative URL path using the parts of a complete Name.

The parts maintain their original case.

Example:

ParseName("example.com/namespace/model:tag+build").URLPath() // returns "/example.com/namespace/model:tag"

func (Name) EqualFold

func (r Name) EqualFold(o Name) bool

EqualFold reports whether r and o are equivalent model names, ignoring case.

func (Name) Filepath

func (r Name) Filepath() string

Filepath returns a complete, canonicalized, relative file path using the parts of a complete Name.

Each parts is downcased, except for the build part which is upcased.

Example:

ParseName("example.com/namespace/model:tag+build").Filepath() // returns "example.com/namespace/model/tag/BUILD"

func (Name) FilepathNoBuild

func (r Name) FilepathNoBuild() string

FilepathNoBuild returns a complete, canonicalized, relative file path using the parts of a complete Name, but without the build part.

func (Name) GoString

func (r Name) GoString() string

GoString implements fmt.GoStringer. It returns a string suitable for debugging and logging. It is similar to Name.DisplayLong but it always returns a string that includes all parts of the Name, with missing parts replaced with a ("?").

func (Name) Host

func (r Name) Host() string

func (Name) IsComplete

func (r Name) IsComplete() bool

IsComplete reports whether the Name is fully qualified. That is it has a domain, namespace, name, tag, and build.

func (Name) IsCompleteNoBuild

func (r Name) IsCompleteNoBuild() bool

IsCompleteNoBuild is like Name.IsComplete but it does not require the build part to be present.

func (Name) IsResolved

func (r Name) IsResolved() bool

IsResolved reports true if the Name has a valid digest.

It is possible to have a valid Name, or a complete Name that is not resolved.

func (Name) IsValid

func (r Name) IsValid() bool

IsValid reports if a model has at minimum a valid model part.

func (Name) IsZero

func (r Name) IsZero() bool

func (Name) LogValue

func (r Name) LogValue() slog.Value

LogValue implements slog.Valuer.

func (Name) MapHash

func (r Name) MapHash() uint64

MapHash returns a case insensitive hash for use in maps and equality checks. For a convenient way to compare names, use Name.EqualFold.

Example

m := map[uint64]bool{}

// key 1
m[ParseNameFill("mistral:latest+q4", FillNothing).MapHash()] = true
m[ParseNameFill("miSTRal:latest+Q4", FillNothing).MapHash()] = true
m[ParseNameFill("mistral:LATest+Q4", FillNothing).MapHash()] = true

// key 2
m[ParseNameFill("mistral:LATest", FillNothing).MapHash()] = true

fmt.Println(len(m))

Output:

2

func (Name) Model

func (r Name) Model() string

func (Name) Namespace

func (r Name) Namespace() string

func (Name) Tag

func (r Name) Tag() string

func (Name) URLPath

func (r Name) URLPath() string

URLPath returns a complete, canonicalized, relative URL path using the parts of a complete Name in the form:

<host>/<namespace>/<model>/<tag>

The parts are downcased.

func (Name) WithBuild

func (r Name) WithBuild(build string) Name

WithBuild returns a copy of r with the build set to the given string.

func (Name) WithDigest

func (r Name) WithDigest(digest Digest) Name

type PartKind

type PartKind int

const (
	PartHost PartKind = iota
	PartNamespace
	PartModel
	PartTag
	PartBuild
	PartDigest

	// NumParts is the number of parts in a Name. In this list, it must
	// follow the final part.
	NumParts

	PartExtraneous = -1
)

Levels of concreteness

func (PartKind) String

func (k PartKind) String() string