model

package
v0.19.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 4, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AnnotationV1WeightName      = "run.cog.weight.name"
	AnnotationV1WeightTarget    = "run.cog.weight.target"
	AnnotationV1WeightSetDigest = "run.cog.weight.set-digest"

	// AnnotationV1WeightSizeUncomp carries an uncompressed byte count.
	// It appears in two places:
	//   - On each layer descriptor inside the weight manifest (§2.5):
	//     the uncompressed size of that single layer's contents. Set by
	//     buildWeightManifestV1 from packedLayer.UncompressedSize.
	//   - On the weight descriptor inside the outer OCI index (§2.6):
	//     the sum across all layers — i.e. the total uncompressed size
	//     of the weight. Set by IndexBuilder.AddWeightDescriptor from
	//     the lockfile entry's Size field.
	AnnotationV1WeightSizeUncomp = "run.cog.weight.size.uncompressed"
)

Manifest-level annotation keys per spec §2.5 (v1 "run.cog.*" namespace).

View Source 
const (
	// DefaultPushConcurrency is the default number of concurrent uploads
	// for both image layers and weight artifacts.
	// This matches Docker's default concurrency for layer uploads, which is a reasonable baseline for OCI pushes as well.
	DefaultPushConcurrency = 5
)
View Source 
const MediaTypeWeightArtifact = "application/vnd.cog.weight.v1"

MediaTypeWeightArtifact is the artifactType on a weight manifest. Layers use standard OCI layer media types; this constant lives on the manifest itself so clients can distinguish weight manifests from image manifests without parsing annotations.

View Source 
const MediaTypeWeightConfig = "application/vnd.cog.weight.config.v1+json"

MediaTypeWeightConfig is the config blob media type per spec §2.1.

View Source 
const PlatformUnknown = "unknown"

PlatformUnknown is the OCI placeholder ("unknown") used for non-platform artifacts such as weight manifests, distinguishing them from the model image manifest in the OCI index.

Variables

View Source 
var (
	LabelConfig          = global.LabelNamespace + "config"
	LabelVersion         = global.LabelNamespace + "version"
	LabelOpenAPISchema   = global.LabelNamespace + "openapi_schema"
	LabelWeightsManifest = global.LabelNamespace + "r8_weights_manifest"
)

Label keys for Cog-specific metadata stored in image labels.

View Source 
var (
	// ErrNotCogModel indicates the image exists but is not a valid Cog model.
	// This occurs when the image lacks the required run.cog.config label.
	ErrNotCogModel = errors.New("image is not a Cog model")

	// ErrNotFound indicates the image was not found in the requested location(s).
	ErrNotFound = errors.New("image not found")
)

Sentinel errors for Resolver operations.

Functions

func GetPushConcurrency added in v0.17.0 

func GetPushConcurrency() int

GetPushConcurrency returns the push concurrency, checking the COG_PUSH_CONCURRENCY environment variable first, then falling back to DefaultPushConcurrency.

func ShortDigest added in v0.19.3 

func ShortDigest(digest string) string

ShortDigest returns the 12-hex-char prefix of a "sha256:…" digest, or the empty string if the input is empty or has no algorithm prefix.

func WeightTag added in v0.17.0 

func WeightTag(name, digest string) string

WeightTag returns the tag for a weight manifest combining name and the short prefix of a digest. digest is "sha256:…"; the 12 hex chars after the algorithm prefix are used. Falls back to "weights-<name>" if digest is empty or missing the algorithm prefix.

Types

type Artifact added in v0.17.0 

type Artifact interface {
	Type() ArtifactType
	Name() string
	Descriptor() v1.Descriptor
}

Artifact is the immutable result of building a spec. It contains the OCI descriptor and enough information for a pusher to upload it.

type ArtifactSpec added in v0.17.0 

type ArtifactSpec interface {
	Type() ArtifactType
	Name() string
}

ArtifactSpec declares what artifact will be produced. It contains all inputs needed to build that artifact. Specs are derived from analyzing the Source (cog.yaml + project directory).

type ArtifactType added in v0.17.0 

type ArtifactType int

ArtifactType identifies the kind of artifact. 

const (
	// ArtifactTypeImage is a container image artifact.
	ArtifactTypeImage ArtifactType = iota + 1
	// ArtifactTypeWeight is a model weight artifact.
	ArtifactTypeWeight
)

func (ArtifactType) String added in v0.17.0 

func (t ArtifactType) String() string

String returns the human-readable name of the artifact type.

type BuildOptions added in v0.17.0 

type BuildOptions struct {
	// ImageName is the output image name (required).
	ImageName string

	// NoCache disables build cache.
	NoCache bool

	// SeparateWeights builds weights as a separate layer.
	SeparateWeights bool

	// Strip removes debug symbols from binaries.
	Strip bool

	// Precompile precompiles Python bytecode.
	Precompile bool

	// UseCudaBaseImage controls CUDA base image usage: "auto", "true", or "false".
	UseCudaBaseImage string

	// UseCogBaseImage controls cog base image usage. nil means auto-detect.
	UseCogBaseImage *bool

	// Secrets are build-time secrets to pass to the build.
	Secrets []string

	// ProgressOutput controls build output format: "auto", "plain", or "tty".
	ProgressOutput string

	// Annotations are extra labels to add to the image.
	Annotations map[string]string

	// SchemaFile is a custom OpenAPI schema file path.
	SchemaFile string

	// DockerfileFile is a custom Dockerfile path.
	DockerfileFile string

	// ExcludeSource skips the COPY . /src step in the generated Dockerfile.
	// Used by `cog serve` to produce an image identical to `cog build` minus
	// the source copy — the source directory is volume-mounted at runtime.
	// All other layers (wheel installs, apt, etc.) are shared with `cog build`
	// via Docker layer caching.
	ExcludeSource bool

	// SkipSchemaValidation skips OpenAPI schema generation and validation.
	// Used by `cog exec` which executes arbitrary commands and may not have
	// a predictor or trainer defined in cog.yaml.
	SkipSchemaValidation bool

	// SkipLabels skips adding Cog metadata labels to the built image.
	// Used by `cog exec`, `cog predict`, `cog serve`, and `cog train` where
	// the image is for local use only and not being distributed.
	SkipLabels bool
}

BuildOptions contains all settings for building a Cog image. This consolidates the many parameters previously passed to image.Build().

func (BuildOptions) WithDefaults added in v0.17.0 

func (o BuildOptions) WithDefaults(src *Source) BuildOptions

WithDefaults returns a copy of BuildOptions with defaults applied from Source. This fills in sensible defaults for any unset fields.

type BuildRef added in v0.17.0 

type BuildRef struct {
	Source  *Source
	Options BuildOptions
}

BuildRef resolves to a Model by building from source. This wraps a Source and BuildOptions for deferred building.

func FromBuild added in v0.17.0 

func FromBuild(src *Source, opts BuildOptions) *BuildRef

FromBuild creates a BuildRef from source and options. Unlike the other From* functions, this does not validate eagerly - validation happens at build time.

type Builder added in v0.17.0 

type Builder interface {
	Build(ctx context.Context, spec ArtifactSpec) (Artifact, error)
}

Builder builds an artifact from a spec. Each builder handles one artifact type (image, weight, etc.).

type BundlePusher added in v0.17.0 

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

BundlePusher pushes an OCI Image Index containing a model image + its weight manifests. It pushes the image, HEAD-checks each weight manifest (which was pushed by `cog weights import`), then assembles the index from the descriptors.

func NewBundlePusher added in v0.17.0 

func NewBundlePusher(docker command.Command, reg registry.Client) *BundlePusher

NewBundlePusher creates a BundlePusher.

func (*BundlePusher) Push added in v0.17.0 

func (p *BundlePusher) Push(ctx context.Context, m *Model, opts PushOptions) error

Push pushes the model as an OCI Index. Weight manifests are verified via HEAD *before* the image is pushed — if any are missing, the push fails fast with a message to re-run import, without leaving an orphaned image in the registry. The image is then pushed via ImagePusher, followed by a HEAD to get its descriptor, and finally the OCI Index is assembled and pushed.

type DockerfileFactory added in v0.17.0 

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

DockerfileFactory wraps existing Dockerfile-based build.

func (*DockerfileFactory) Build added in v0.17.0 

func (f *DockerfileFactory) Build(ctx context.Context, src *Source, opts BuildOptions) (*ImageArtifact, error)

Build delegates to the existing image.Build() function.

func (*DockerfileFactory) Name added in v0.17.0 

func (f *DockerfileFactory) Name() string

Name returns the factory name.

type Factory added in v0.17.0 

type Factory interface {
	// Build creates a Docker image from source and returns ImageArtifact metadata.
	// For dev mode (cog serve), set ExcludeSource=true in BuildOptions to skip
	// COPY . /src — the source directory is volume-mounted at runtime instead.
	Build(ctx context.Context, src *Source, opts BuildOptions) (*ImageArtifact, error)

	// Name returns the factory name for logging/debugging.
	Name() string
}

Factory is the build backend interface. Different implementations handle different build strategies.

func NewDockerfileFactory added in v0.17.0 

func NewDockerfileFactory(docker command.Command, registry registry.Client) Factory

NewDockerfileFactory creates a Factory that uses the existing Dockerfile-based build.

type ImageArtifact added in v0.17.0 

type ImageArtifact struct {

	// Image metadata
	Reference string            // Full image reference (e.g., "r8.im/user/model:latest")
	Digest    string            // Content-addressable digest (sha256:...)
	Labels    map[string]string // Docker/OCI image labels
	Platform  *Platform         // OS/architecture
	Source    ImageSource       // Where loaded from (local/remote/build)
	// contains filtered or unexported fields
}

ImageArtifact represents an OCI container image. It serves as both the build artifact (in Model.Artifacts) and the general-purpose image metadata type throughout the codebase. It implements the Artifact interface.

func NewImageArtifact added in v0.17.0 

func NewImageArtifact(name string, desc v1.Descriptor, reference string) *ImageArtifact

NewImageArtifact creates an ImageArtifact from a build result.

func (*ImageArtifact) CogVersion added in v0.17.0 

func (a *ImageArtifact) CogVersion() string

CogVersion returns the Cog version that built this image, or empty string if not set.

func (*ImageArtifact) Config added in v0.17.0 

func (a *ImageArtifact) Config() string

Config returns the raw cog.yaml config stored in image labels, or empty string if not set.

func (*ImageArtifact) Descriptor added in v0.17.0 

func (a *ImageArtifact) Descriptor() v1.Descriptor

Descriptor returns the OCI descriptor for this image.

func (*ImageArtifact) IsCogModel added in v0.17.0 

func (a *ImageArtifact) IsCogModel() bool

IsCogModel returns true if this image has Cog labels indicating it's a Cog model.

func (*ImageArtifact) Name added in v0.17.0 

func (a *ImageArtifact) Name() string

Name returns the artifact's logical name.

func (*ImageArtifact) OpenAPISchema added in v0.17.0 

func (a *ImageArtifact) OpenAPISchema() string

OpenAPISchema returns the OpenAPI schema stored in image labels, or empty string if not set.

func (*ImageArtifact) ParsedConfig added in v0.17.0 

func (a *ImageArtifact) ParsedConfig() (*config.Config, error)

ParsedConfig returns the parsed cog.yaml config from image labels. Returns nil without error if no config label is present. Returns error if the label contains invalid JSON.

func (*ImageArtifact) ParsedOpenAPISchema added in v0.17.0 

func (a *ImageArtifact) ParsedOpenAPISchema() (*openapi3.T, error)

ParsedOpenAPISchema returns the parsed OpenAPI schema from image labels. Returns nil without error if no schema label is present. Returns error if the label contains invalid JSON.

func (*ImageArtifact) ToModel added in v0.17.0 

func (a *ImageArtifact) ToModel() (*Model, error)

ToModel converts the ImageArtifact to a Model by parsing its labels. Returns error if the image is not a valid Cog model or if labels contain invalid JSON.

func (*ImageArtifact) Type added in v0.17.0 

func (a *ImageArtifact) Type() ArtifactType

Type returns ArtifactTypeImage.

type ImageBuilder added in v0.17.0 

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

ImageBuilder builds an ImageArtifact from an ImageSpec. It delegates to a Factory for the docker build, inspects the result to populate labels and the canonical digest, and returns a fully populated ImageArtifact.

func NewImageBuilder added in v0.17.0 

func NewImageBuilder(factory Factory, docker command.Command, source *Source, opts BuildOptions) *ImageBuilder

NewImageBuilder creates an ImageBuilder.

func (*ImageBuilder) Build added in v0.17.0 

func (b *ImageBuilder) Build(ctx context.Context, spec ArtifactSpec) (Artifact, error)

Build builds an ImageArtifact from an ImageSpec. It delegates to the Factory for the docker build, inspects the result to populate labels and the canonical digest, and returns a fully populated ImageArtifact.

type ImagePushOption added in v0.17.0 

type ImagePushOption func(*imagePushOptions)

ImagePushOption is a functional option for configuring ImagePusher.Push.

func WithOnFallback added in v0.17.0 

func WithOnFallback(fn func()) ImagePushOption

WithOnFallback sets a callback invoked when OCI push fails and the push is about to fall back to Docker push. This allows the caller to clean up any OCI-specific progress display before Docker push starts its own output.

func WithProgressFn added in v0.17.0 

func WithProgressFn(fn func(PushProgress)) ImagePushOption

WithProgressFn sets a callback for reporting per-layer upload progress.

type ImagePusher added in v0.17.0 

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

ImagePusher pushes container images to a registry.

It first attempts an OCI chunked push (export from Docker -> tarball -> push layers via registry client), then falls back to Docker's native push on any non-fatal error. This bypasses size limits on Docker's monolithic push path while maintaining backwards compatibility.

func (*ImagePusher) Push added in v0.17.0 

func (p *ImagePusher) Push(ctx context.Context, artifact *ImageArtifact, opts ...ImagePushOption) error

Push pushes a container image to the registry.

Tries the OCI chunked push path first (if enabled and registry client is available), then falls back to Docker push on any non-fatal error. The artifact must have a valid Reference.

type ImageSource added in v0.17.0 

type ImageSource string

ImageSource indicates where an image was loaded from. 

const (
	ImageSourceLocal  ImageSource = "local"  // Docker daemon
	ImageSourceRemote ImageSource = "remote" // Registry
	ImageSourceBuild  ImageSource = "build"  // Just built
)

type ImageSpec added in v0.17.0 

type ImageSpec struct {
	ImageName string
	Secrets   []string
	NoCache   bool
	// contains filtered or unexported fields
}

ImageSpec declares an image to be built. It implements ArtifactSpec.

TODO: ImageBuilder currently reads build options from BuildOptions (passed at construction) rather than from ImageSpec fields. When the build pipeline fully migrates to specs, ImageName/Secrets/NoCache should be the source of truth.

func NewImageSpec added in v0.17.0 

func NewImageSpec(name, imageName string, opts ...ImageSpecOption) *ImageSpec

NewImageSpec creates an ImageSpec with the given name and image name. Optional configuration can be provided via ImageSpecOption functions.

func (*ImageSpec) Name added in v0.17.0 

func (s *ImageSpec) Name() string

Name returns the spec's logical name.

func (*ImageSpec) Type added in v0.17.0 

func (s *ImageSpec) Type() ArtifactType

Type returns ArtifactTypeImage.

type ImageSpecOption added in v0.17.0 

type ImageSpecOption func(*ImageSpec)

ImageSpecOption configures optional fields on ImageSpec.

func WithImageNoCache added in v0.17.0 

func WithImageNoCache(noCache bool) ImageSpecOption

WithImageNoCache disables build cache for the image build.

func WithImageSecrets added in v0.17.0 

func WithImageSecrets(secrets []string) ImageSpecOption

WithImageSecrets sets build-time secrets for the image build.

type IndexBuilder added in v0.17.0 

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

IndexBuilder builds an OCI Image Index from pre-pushed manifest descriptors.

func NewIndexBuilder added in v0.17.0 

func NewIndexBuilder() *IndexBuilder

NewIndexBuilder creates a new index builder.

func (*IndexBuilder) AddWeightDescriptor added in v0.17.0 

func (b *IndexBuilder) AddWeightDescriptor(desc v1.Descriptor, name, setDigest string, uncompressedSize int64)

AddWeightDescriptor adds a weight manifest descriptor. Metadata (name, setDigest, uncompressedSize) is hoisted into index-level annotations so the index is inspectable without fetching child manifests (§2.6).

func (*IndexBuilder) BuildFromDescriptors added in v0.17.0 

func (b *IndexBuilder) BuildFromDescriptors() (v1.ImageIndex, error)

BuildFromDescriptors creates an OCI Image Index from pre-pushed manifest descriptors. This works with bare descriptors returned from push operations, avoiding the need to fetch images back from the registry.

func (*IndexBuilder) SetImageDescriptor added in v0.17.0 

func (b *IndexBuilder) SetImageDescriptor(desc v1.Descriptor, platform *v1.Platform)

SetImageDescriptor sets the image manifest descriptor.

type LayerStatus added in v0.19.3 

type LayerStatus string

LayerStatus describes the registry presence of a single layer. 

const (
	LayerStatusReady   LayerStatus = "ready"
	LayerStatusMissing LayerStatus = "missing"
)

type LayerStatusResult added in v0.19.3 

type LayerStatusResult struct {
	Digest string
	Size   int64
	Status LayerStatus
}

LayerStatusResult is one layer's status in the registry.

type LocalRef added in v0.17.0 

type LocalRef struct {
	Parsed *ParsedRef
}

LocalRef resolves an image from the local docker daemon only. It will not fall back to remote registry if the image is not found locally.

func FromLocal added in v0.17.0 

func FromLocal(ref string) (*LocalRef, error)

FromLocal parses and validates a reference for local resolution. Returns an error immediately if the reference is invalid.

type Model 

type Model struct {
	Image      *ImageArtifact // Underlying OCI image
	Config     *config.Config // Parsed cog.yaml
	Schema     *openapi3.T    // OpenAPI schema
	CogVersion string         // Version of cog used to build

	// Artifacts is the collection of all artifacts produced by building this model.
	// Populated by Resolver.Build(). Contains ImageArtifact instances only.
	Artifacts []Artifact

	// Weights are the model's managed weights, loaded from the lockfile
	// during Build. Each Weight carries all lockfile metadata (name,
	// target, digest, set digest, sizes). The push path uses these to
	// HEAD-check weight manifests in the registry; it never streams
	// layer bytes.
	Weights []Weight
}

Model represents a Cog model extracted from an image.

func (*Model) ArtifactsByType added in v0.17.0 

func (m *Model) ArtifactsByType(t ArtifactType) []Artifact

ArtifactsByType returns all artifacts matching the given type.

func (*Model) GetImageArtifact added in v0.17.0 

func (m *Model) GetImageArtifact() *ImageArtifact

GetImageArtifact returns the first ImageArtifact from the artifacts collection, or nil if none exists.

func (*Model) HasGPU added in v0.17.0 

func (m *Model) HasGPU() bool

HasGPU returns true if the model requires GPU.

func (*Model) ImageRef added in v0.17.0 

func (m *Model) ImageRef() string

ImageRef returns the image reference string, or empty string if no image.

func (*Model) IsBundle added in v0.17.0 

func (m *Model) IsBundle() bool

IsBundle returns true if this model has managed weights.

func (*Model) SchemaJSON added in v0.17.0 

func (m *Model) SchemaJSON() ([]byte, error)

SchemaJSON returns the OpenAPI schema as JSON bytes, or nil if no schema.

func (*Model) WeightArtifacts added in v0.17.0 

func (m *Model) WeightArtifacts() []*WeightArtifact

WeightArtifacts returns all WeightArtifact instances from the artifacts collection.

type Option added in v0.17.0 

type Option func(*options)

Option configures how Resolver methods behave.

func LocalOnly added in v0.17.0 

func LocalOnly() Option

LocalOnly loads only from the local docker daemon. Returns an error if the image is not found locally.

func PreferLocal added in v0.17.0 

func PreferLocal() Option

PreferLocal tries local docker daemon first, falls back to remote on not-found.

func PreferRemote added in v0.17.0 

func PreferRemote() Option

PreferRemote tries remote registry first, falls back to local on not-found. This is the default behavior.

func RemoteOnly added in v0.17.0 

func RemoteOnly() Option

RemoteOnly loads only from the remote registry. Does not check the local docker daemon.

func WithPlatform added in v0.17.0 

func WithPlatform(p *registry.Platform) Option

WithPlatform sets the platform for remote registry queries.

type ParseOption added in v0.17.0 

type ParseOption func(*parseOptions)

ParseOption configures how image references are parsed.

func Insecure added in v0.17.0 

func Insecure() ParseOption

Insecure allows parsing references to registries that use HTTP or have invalid/self-signed certificates. Use this for local development registries like localhost:5000.

func WithDefaultRegistry added in v0.17.0 

func WithDefaultRegistry(registry string) ParseOption

WithDefaultRegistry sets the registry to use when the reference doesn't include one. By default, Docker Hub (index.docker.io) is used.

func WithDefaultTag added in v0.17.0 

func WithDefaultTag(tag string) ParseOption

WithDefaultTag sets the tag to use when the reference doesn't include one. By default, "latest" is used.

type ParsedRef added in v0.17.0 

type ParsedRef struct {
	// Original is the input string before parsing.
	Original string

	// Ref is the underlying parsed reference from go-containerregistry.
	Ref name.Reference
}

ParsedRef wraps a validated and parsed image reference.

func ParseRef added in v0.17.0 

func ParseRef(ref string, opts ...ParseOption) (*ParsedRef, error)

ParseRef validates and parses an image reference.

func (*ParsedRef) Digest added in v0.17.0 

func (p *ParsedRef) Digest() string

Digest returns the digest (e.g., "sha256:...") or empty string if this is a tag reference.

func (*ParsedRef) IsDigest added in v0.17.0 

func (p *ParsedRef) IsDigest() bool

IsDigest returns true if the reference includes a digest.

func (*ParsedRef) IsReplicate added in v0.17.0 

func (p *ParsedRef) IsReplicate() bool

IsReplicate returns true if the registry is the Replicate registry (r8.im).

func (*ParsedRef) IsTag added in v0.17.0 

func (p *ParsedRef) IsTag() bool

IsTag returns true if the reference includes a tag.

func (*ParsedRef) Registry added in v0.17.0 

func (p *ParsedRef) Registry() string

Registry returns the registry host (e.g., "r8.im", "index.docker.io").

func (*ParsedRef) Repository added in v0.17.0 

func (p *ParsedRef) Repository() string

Repository returns the repository path (e.g., "user/model", "library/nginx").

func (*ParsedRef) String added in v0.17.0 

func (p *ParsedRef) String() string

String returns the fully-qualified canonical reference string.

func (*ParsedRef) Tag added in v0.17.0 

func (p *ParsedRef) Tag() string

Tag returns the tag (e.g., "v1", "latest") or empty string if this is a digest reference.

type Platform added in v0.17.0 

type Platform struct {
	OS           string
	Architecture string
	Variant      string
}

Platform describes the OS and architecture of an image.

type PushOptions added in v0.17.0 

type PushOptions struct {
	// Platform specifies the target platform for bundle indexes.
	// Default: linux/amd64
	Platform *Platform

	// ImageProgressFn is an optional callback for reporting push progress.
	// It receives both phase transitions (Phase set, byte fields zero) and
	// per-layer byte progress (Phase empty, Complete/Total set).
	ImageProgressFn func(PushProgress)

	// OnFallback is called when OCI push fails and the push is about to fall
	// back to Docker push. This allows the caller to clean up any OCI-specific
	// progress display before Docker push starts its own output.
	OnFallback func()
}

PushOptions configures push behavior.

type PushPhase added in v0.18.0 

type PushPhase string

PushPhase represents a phase of the push process. The image pusher reports phase transitions so the CLI can display appropriate progress indicators (e.g., a status line during export, progress bars during push). 

const (
	// PushPhaseExporting indicates the image is being exported from the Docker
	// daemon to a local tarball. This phase has no granular progress — the
	// caller typically shows an indeterminate status indicator.
	PushPhaseExporting PushPhase = "exporting"

	// PushPhasePushing indicates layers are being pushed to the registry.
	// During this phase, per-layer progress is reported via PushProgress callbacks.
	PushPhasePushing PushPhase = "pushing"
)

type PushProgress added in v0.17.0 

type PushProgress struct {
	// Phase indicates a push phase transition. When set, this is a phase-only
	// update and the byte progress fields should be ignored.
	Phase PushPhase
	// LayerDigest identifies which layer this progress is for.
	// Empty for phase transitions and single-layer pushes (e.g., weight uploads).
	LayerDigest string
	// Complete is the number of bytes uploaded so far.
	Complete int64
	// Total is the total number of bytes to upload.
	Total int64
}

PushProgress reports progress for a push operation.

There are two kinds of updates:

  • Phase transitions: Phase is set, byte fields are zero. Indicates the push has moved to a new phase (e.g., exporting image, pushing layers).
  • Byte progress: Phase is empty, Complete/Total track upload progress for a specific layer or blob identified by LayerDigest.

Used by both ImagePusher (container image layers) and WeightPusher (weight blobs).

type Ref added in v0.17.0 

type Ref interface {
	// contains filtered or unexported methods
}

Ref represents something that can be resolved to a Model. This interface enables declarative model resolution - callers specify "what they have" (a tag, local image, or source to build) and the Resolver figures out how to produce a Model.

type RemoteRef added in v0.17.0 

type RemoteRef struct {
	Parsed *ParsedRef
}

RemoteRef resolves an image from a remote registry only. It will not check the local docker daemon.

func FromRemote added in v0.17.0 

func FromRemote(ref string) (*RemoteRef, error)

FromRemote parses and validates a reference for remote resolution. Returns an error immediately if the reference is invalid.

type Resolver added in v0.17.0 

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

Resolver orchestrates building and loading Models.

func NewResolver added in v0.17.0 

func NewResolver(docker command.Command, reg registry.Client) *Resolver

NewResolver creates a Resolver with the default factory.

func (*Resolver) Build added in v0.17.0 

func (r *Resolver) Build(ctx context.Context, src *Source, opts BuildOptions) (*Model, error)

Build creates a Model by building from source.

func (*Resolver) Inspect added in v0.17.0 

func (r *Resolver) Inspect(ctx context.Context, ref *ParsedRef, opts ...Option) (*Model, error)

Inspect returns Model metadata for a parsed ref without pulling. By default (PreferLocal), tries local docker daemon first, then remote registry. Only falls back on "not found" errors; real errors (docker down, auth) are surfaced. Returns ErrNotCogModel if the image is not a valid Cog model.

func (*Resolver) InspectByID added in v0.17.0 

func (r *Resolver) InspectByID(ctx context.Context, id string) (*Model, error)

InspectByID returns Model metadata from the local docker daemon by image ID. This supports both full IDs (sha256:...) and short IDs (e.g., "9056219a5fb2"). Use this when you have an image ID rather than a tagged reference. Returns ErrNotCogModel if the image is not a valid Cog model.

func (*Resolver) Pull added in v0.17.0 

func (r *Resolver) Pull(ctx context.Context, ref *ParsedRef, opts ...Option) (*Model, error)

Pull ensures a Model is locally available for running. It first checks if the image exists locally. If not, it pulls from the registry. Returns ErrNotCogModel if the image is not a valid Cog model. Returns ErrNotFound if the image cannot be found locally or remotely.

func (*Resolver) Push added in v0.17.0 

func (r *Resolver) Push(ctx context.Context, m *Model, opts PushOptions) error

Push pushes a Model to a container registry.

Uses the OCI chunked push path (via ImagePusher) which bypasses Docker's monolithic push and supports layers of any size through chunked uploads. Falls back to legacy Docker push if OCI push is not available.

func (*Resolver) Resolve added in v0.17.0 

func (r *Resolver) Resolve(ctx context.Context, ref Ref) (*Model, error)

Resolve resolves any Ref to a Model. This is the main entry point for declarative model resolution.

func (*Resolver) WithFactory added in v0.17.0 

func (r *Resolver) WithFactory(f Factory) *Resolver

WithFactory sets a custom factory and returns the Resolver for chaining.

type Source added in v0.17.0 

type Source struct {
	Config         *config.Config
	ProjectDir     string
	ConfigFilename string // Base filename like "cog.yaml" or "my-config.yaml"
	Warnings       []config.DeprecationWarning
}

Source represents a Cog project ready to build. It combines the parsed configuration with the project directory location.

func NewSource added in v0.17.0 

func NewSource(configPath string) (*Source, error)

NewSource loads configuration from the given path and returns a Source. The configPath can be a filename (e.g., "cog.yaml") which will be searched for in the current directory and parent directories.

func NewSourceFromConfig added in v0.17.0 

func NewSourceFromConfig(cfg *config.Config, projectDir string) *Source

NewSourceFromConfig creates a Source from an existing Config. Use this when you already have a parsed config and know the project directory.

func (*Source) ArtifactSpecs added in v0.17.0 

func (s *Source) ArtifactSpecs() ([]ArtifactSpec, error)

ArtifactSpecs returns the artifact declarations derived from this source: one ImageSpec plus one WeightSpec per configured weight. Returns an error if any weight's source URI is malformed. Returns (nil, nil) if Config is nil.

type TagRef added in v0.17.0 

type TagRef struct {
	Parsed *ParsedRef
}

TagRef resolves an image by tag or digest reference. It uses the default Load behavior: try remote registry first, then fall back to local docker daemon if not found remotely.

func FromTag added in v0.17.0 

func FromTag(ref string) (*TagRef, error)

FromTag parses and validates a tag reference. Returns an error immediately if the reference is invalid.

type Weight added in v0.19.3 

type Weight struct {
	Name      string
	Target    string
	Digest    string // OCI manifest digest
	SetDigest string // content-addressable file set identity (spec §2.4)
	Size      int64
	// SizeCompressed is the total compressed (over-the-wire) size.
	SizeCompressed int64
}

Weight is the model's representation of a managed weight, projected from a lockfile entry. Fields mirror lockfile.WeightLockEntry but this type belongs to the model domain and carries only what the build and push paths need.

func WeightFromLockEntry added in v0.19.3 

func WeightFromLockEntry(e lockfile.WeightLockEntry) Weight

WeightFromLockEntry creates a Weight from a lockfile entry.

func WeightsFromLockfile added in v0.19.3 

func WeightsFromLockfile(projectDir string) ([]Weight, error)

WeightsFromLockfile loads a lockfile from projectDir and returns the corresponding Weight slice. Returns an error if the lockfile is missing or corrupt.

type WeightArtifact added in v0.17.0 

type WeightArtifact struct {

	// Entry is the lockfile entry describing this weight's metadata.
	// Must not be mutated after construction.
	Entry lockfile.WeightLockEntry

	// Layers are the packed layer descriptors. The pusher reads bytes
	// for each layer by replaying its layerPlan against store; their
	// metadata (digest, size, mediaType) matches Entry.Layers.
	Layers []packedLayer
	// contains filtered or unexported fields
}

WeightArtifact is a built weight artifact ready to push as an OCI manifest. It implements Artifact.

The lockfile entry (Entry) is the single source of truth for all metadata. Each layer carries its layerPlan; layer bytes are reproduced on demand by streaming from store at push time.

func (*WeightArtifact) Descriptor added in v0.17.0 

func (a *WeightArtifact) Descriptor() v1.Descriptor

func (*WeightArtifact) Name added in v0.17.0 

func (a *WeightArtifact) Name() string

func (*WeightArtifact) TotalSize added in v0.19.3 

func (a *WeightArtifact) TotalSize() int64

TotalSize returns the sum of all layer blob sizes (bytes over the wire).

func (*WeightArtifact) Type added in v0.17.0 

func (a *WeightArtifact) Type() ArtifactType

type WeightBuilder added in v0.17.0 

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

WeightBuilder is the weight factory: given a WeightSpec (source URI + target), it ingresses the source files into the local content-addressed store, plans tar layers, derives layer digests (cache-fast or recompute), assembles the v1 OCI manifest, and returns a WeightArtifact carrying the layer descriptors and manifest digest.

`cog weights import` ≡ `cog weights import + cog weights pull` — the build path leaves the local store warm so subsequent `cog predict` invocations can hardlink-assemble without a separate pull.

The builder is offline: it never talks to a registry. The manifest digest it writes into the artifact descriptor is a sha256 of the serialized manifest bytes.

func NewWeightBuilder added in v0.17.0 

func NewWeightBuilder(source *Source, st store.Store, lockPath string) *WeightBuilder

NewWeightBuilder creates a WeightBuilder.

st is the local content-addressed weight store. lockPath is where weights.lock is read/written.

func (*WeightBuilder) Build added in v0.17.0 

func (b *WeightBuilder) Build(ctx context.Context, spec ArtifactSpec) (Artifact, error)

Build runs the full import pipeline for one weight:

  1. Inventory the source.
  2. Ingress every file into the local store (skipping already-present digests). Hash mismatches surface here.
  3. Decide whether to trust the lockfile's recorded layer digests (fast path) or recompute them by streaming from the store (recompute path).
  4. Assemble the OCI manifest.
  5. Stamp the current envelope format into the lockfile and rewrite it iff anything actually changed.

The push path is independent of Build; the caller is responsible for handing the returned artifact to the pusher (which checks per-layer with BlobExists before uploading).

func (*WeightBuilder) BuildFromPlan added in v0.19.3 

func (b *WeightBuilder) BuildFromPlan(ctx context.Context, spec ArtifactSpec, plan *WeightImportPlan) (Artifact, error)

BuildFromPlan is like Build but reuses a pre-computed inventory from PlanImport, avoiding a second walk/hash of the source.

func (*WeightBuilder) PlanImport added in v0.19.3 

func (b *WeightBuilder) PlanImport(ctx context.Context, ws *WeightSpec) (*WeightImportPlan, error)

PlanImport runs the inventory + filter steps for one weight without ingressing, packing, or pushing. It compares the result against the existing lockfile to determine what would change on a real import.

type WeightConfigBlob added in v0.19.3 

type WeightConfigBlob struct {
	Name      string             `json:"name"`
	Target    string             `json:"target"`
	SetDigest string             `json:"setDigest"`
	Files     []WeightConfigFile `json:"files"`
}

WeightConfigBlob is the JSON structure for the config blob (§2.3).

type WeightConfigFile added in v0.19.3 

type WeightConfigFile struct {
	Path   string `json:"path"`
	Layer  string `json:"layer"`
	Size   int64  `json:"size"`
	Digest string `json:"digest"`
}

WeightConfigFile is one entry in the config blob's files array.

type WeightImportPlan added in v0.19.3 

type WeightImportPlan struct {
	Spec *WeightSpec

	Status  WeightImportPlanStatus
	Changes []string // human-readable list of what changed

	// Resolved is the pre-computed inventory from planning. Build can
	// reuse this to avoid re-walking the source.
	Resolved *resolvedInventory

	// UnfilteredFiles is populated when include/exclude patterns are
	// active, so the caller can show what was excluded.
	UnfilteredFiles []weightsource.InventoryFile
}

WeightImportPlan is the result of planning one weight's import without executing it. It contains everything needed to show the user what would happen and to pass pre-computed inventory into Build.

func (*WeightImportPlan) ExcludedFiles added in v0.19.3 

func (p *WeightImportPlan) ExcludedFiles() []weightsource.InventoryFile

ExcludedFiles returns files that were in the unfiltered inventory but not in the filtered set.

func (*WeightImportPlan) FilteredFiles added in v0.19.3 

func (p *WeightImportPlan) FilteredFiles() []weightsource.InventoryFile

FilteredFiles returns the filtered inventory files.

func (*WeightImportPlan) TotalSize added in v0.19.3 

func (p *WeightImportPlan) TotalSize() int64

TotalSize returns the sum of filtered file sizes.

type WeightImportPlanStatus added in v0.19.3 

type WeightImportPlanStatus string

WeightImportPlanStatus describes what would happen to a weight on import. 

const (
	PlanStatusNew             WeightImportPlanStatus = "new"
	PlanStatusUnchanged       WeightImportPlanStatus = "unchanged"
	PlanStatusConfigChanged   WeightImportPlanStatus = "config-changed"
	PlanStatusUpstreamChanged WeightImportPlanStatus = "upstream-changed"
)

type WeightLayerProgress added in v0.19.3 

type WeightLayerProgress struct {
	WeightName  string
	LayerDigest string
	Complete    int64
	Total       int64
}

WeightLayerProgress reports per-layer progress for a weight push. When dispatched by BundlePusher, WeightName identifies which artifact the layer belongs to; the per-weight WeightPusher.Push path leaves it empty.

type WeightPushOptions added in v0.17.0 

type WeightPushOptions struct {
	// Concurrency is the maximum number of layers to upload in parallel.
	// If <= 0, GetPushConcurrency() is used.
	Concurrency int
	// Tag overrides the manifest tag. Defaults to
	// WeightTag(artifact.Name, tagSeed) where tagSeed is the set digest.
	Tag string
	// ProgressFn is an optional callback for per-layer upload progress.
	ProgressFn func(WeightLayerProgress)
	// RetryFn is an optional retry callback, invoked per-layer.
	// Return false to abort the retry.
	RetryFn func(WeightRetryEvent) bool
}

WeightPushOptions configures a weight push.

type WeightPushResult added in v0.17.0 

type WeightPushResult struct {
	// Ref is the full image reference the manifest was pushed to
	// (e.g. "registry/repo:weights-name-abc123").
	Ref string
	// Descriptor is the OCI descriptor for the pushed manifest.
	Descriptor v1.Descriptor
}

WeightPushResult describes a successful weight push.

type WeightPusher added in v0.17.0 

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

WeightPusher pushes a WeightArtifact as a v1 multi-layer OCI artifact. Each tar layer is uploaded via registry.WriteLayer (which supports multipart uploads, progress, and retry), followed by the manifest via registry.PushImage. Layers upload concurrently, bounded by GetPushConcurrency.

func NewWeightPusher added in v0.17.0 

func NewWeightPusher(reg registry.Client) *WeightPusher

NewWeightPusher creates a new WeightPusher.

func (*WeightPusher) Push added in v0.17.0 

func (p *WeightPusher) Push(ctx context.Context, repo string, artifact *WeightArtifact, opts ...WeightPushOptions) (*WeightPushResult, error)

Push pushes a WeightArtifact to the registry as a v1 OCI weight manifest. Layers upload concurrently; the manifest goes up last.

The artifact owns the content-addressed store from which layer bytes are streamed; Push reads through that store on each upload (and on retry) without keeping any tar bytes in memory or on disk. On layer-upload failure the manifest is not attempted, but any already-uploaded layers remain in the registry (garbage-collectable).

type WeightRetryEvent added in v0.17.0 

type WeightRetryEvent struct {
	// Name identifies which layer is being retried. It combines the weight
	// name and layer digest, e.g. "z-image-turbo layer sha256:abc…".
	Name        string
	Attempt     int
	MaxAttempts int
	Err         error
	NextRetryIn time.Duration
}

WeightRetryEvent reports a retry attempt for a weight layer upload.

type WeightSpec added in v0.17.0 

type WeightSpec struct {
	Target  string   // container mount path
	URI     string   // normalized source URI (file://./weights, hf://org/repo)
	Include []string // sorted glob patterns
	Exclude []string // sorted glob patterns
	// contains filtered or unexported fields
}

WeightSpec is the normalized, user-declared description of a weight: target mount path, source URI, and include/exclude filters. Construct via WeightSpecFromConfig or WeightSpecFromLock; compare with Equal.

Include and Exclude are sorted at construction time. They describe a set of glob patterns applied by the packer, so order is not part of the user's intent — reordering patterns in cog.yaml must not trigger a rebuild.

func WeightSpecFromConfig added in v0.19.3 

func WeightSpecFromConfig(w config.WeightSource) (*WeightSpec, error)

WeightSpecFromConfig builds a WeightSpec from a cog.yaml weight entry, normalizing the URI and cloning+sorting Include/Exclude. Returns an error if the URI is empty or uses an unknown scheme.

func WeightSpecFromLock added in v0.19.3 

func WeightSpecFromLock(e lockfile.WeightLockEntry) *WeightSpec

WeightSpecFromLock extracts the user-intent fields (target, URI, include/exclude) from a lockfile entry. Fields are copied as stored: no re-normalization. A lockfile whose on-disk form differs from what we would write today — whether in URI form, include/exclude order, or anything else — must report as drift so the next build rewrites it.

func (*WeightSpec) ConfigWeight added in v0.19.3 

func (s *WeightSpec) ConfigWeight() lockfile.ConfigWeight

ConfigWeight returns the lockfile-package representation of this spec for drift comparison. This is the single mapping point between WeightSpec and lockfile.ConfigWeight — adding a user-intent field to WeightSpec requires updating this method, and the compiler will surface any field mismatches.

func (*WeightSpec) Equal added in v0.19.3 

func (s *WeightSpec) Equal(other *WeightSpec) bool

Equal reports whether two specs describe the same user intent. Name is excluded: callers only compare specs for the same weight name.

func (*WeightSpec) Name added in v0.17.0 

func (s *WeightSpec) Name() string

func (*WeightSpec) Type added in v0.17.0 

func (s *WeightSpec) Type() ArtifactType

type WeightStatus added in v0.19.3 

type WeightStatus string

WeightStatus describes the resolved status of a weight. 

const (
	WeightStatusReady      WeightStatus = "ready"
	WeightStatusIncomplete WeightStatus = "incomplete"
	WeightStatusStale      WeightStatus = "stale"
	WeightStatusPending    WeightStatus = "pending"
	WeightStatusOrphaned   WeightStatus = "orphaned"
)

type WeightStatusResult added in v0.19.3 

type WeightStatusResult struct {
	Name      string
	Target    string
	Status    WeightStatus
	LockEntry *lockfile.WeightLockEntry
	Layers    []LayerStatusResult
}

WeightStatusResult is one weight's resolved status. The LockEntry pointer is nil for pending weights; non-nil for all other statuses. Layers is populated only for weights that had registry checks performed.

type WeightsStatus added in v0.19.3 

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

WeightsStatus is the computed status of all weights for a model. It is the return value of ComputeWeightsStatus and provides methods to inspect the results.

func ComputeWeightsStatus added in v0.19.3 

func ComputeWeightsStatus(ctx context.Context, cfg *config.Config, lock *lockfile.WeightsLock, repo string, reg registry.Client) (*WeightsStatus, error)

ComputeWeightsStatus determines the status of every weight by matching config declarations against the lockfile and checking the registry for per-layer blob presence.

Registry checks run concurrently, bounded by GetPushConcurrency(). Per-weight registry errors are soft: the weight is marked "incomplete" and layers are marked "missing". Context cancellation is propagated via errgroup and returns an error.

func (*WeightsStatus) AllReady added in v0.19.3 

func (ws *WeightsStatus) AllReady() bool

AllReady reports whether every weight is in the "ready" state. Returns true for empty weight lists.

func (*WeightsStatus) ByStatus added in v0.19.3 

func (ws *WeightsStatus) ByStatus(status WeightStatus) []WeightStatusResult

ByStatus returns all results with the given status.

func (*WeightsStatus) Results added in v0.19.3 

func (ws *WeightsStatus) Results() []WeightStatusResult

Results returns all weight status results in order: config-declared weights first (preserving cog.yaml order), then orphaned lockfile entries.

Source Files

View all Source files

Directories

Path Synopsis
Package weightsource is the pluggable source layer for weight imports.
 Package weightsource is the pluggable source layer for weight imports.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.