store

Documentation

Overview

Package store manages Exedra models in a local store: it fetches them from an OCI registry and keeps them up to date; without a configured repo it still serves the local store.

A Client is safe for concurrent use. Mutations hold a per-model lock shared across processes; readers take no locks and always see a complete install.

Index

• Constants
• Variables
• type Client
  • func New(opts Options) (*Client, error)
  • func (c *Client) Check(ctx context.Context, id string) ([]Update, error)
  • func (c *Client) Current(id string) (*State, error)
  • func (c *Client) Index(ctx context.Context) (*Index, error)
  • func (c *Client) Info(ctx context.Context, idOrRef string) (kf *KitFile, digest string, err error)
  • func (c *Client) Install(ctx context.Context, idOrRef string, progress func(Progress)) (*State, error)
  • func (c *Client) Installed() ([]*State, error)
  • func (c *Client) ModelPath(st *State) (string, error)
  • func (c *Client) Prune(ctx context.Context, id string, keep int) ([]string, error)
  • func (c *Client) Remove(ctx context.Context, id, version string) error
  • func (c *Client) RemoveAll(ctx context.Context, id string) error
  • func (c *Client) Rollback(ctx context.Context, id string) (*State, error)
  • func (c *Client) Root() string
  • func (c *Client) SwitchCurrent(ctx context.Context, id, version string) error
  • func (c *Client) Update(ctx context.Context, id string, progress func(Progress)) ([]*State, error)
  • func (c *Client) Verify(id string) (*VerifyReport, error)
  • func (c *Client) Versions(id string) ([]string, error)
• type Exedra
  • func (e Exedra) SupportsLanguage(lang string) bool
• type FileDigest
• type Index
  • func (i *Index) Lookup(id string) (IndexEntry, bool)
• type IndexEntry
• type KitFile
• type KitModel
• type KitPackage
• type KitParameters
• type Options
• type Progress
• type ProgressStep
• type State
  • func (s *State) ModelFiles() []string
  • func (s *State) Size() int64
• type StateLayer
• type Update
• type VerifyReport
  • func (r *VerifyReport) Intact() bool

Constants

const IndexName = "exedra-index"

IndexName is the catalog artifact name within the repo.

Variables

var (
	ErrNotInstalled     = errors.New("model is not installed")
	ErrNotInIndex       = errors.New("model is not present in the index")
	ErrInvalidIndex     = errors.New("invalid model index")
	ErrDigestMismatch   = errors.New("digest mismatch")
	ErrArtifactMismatch = errors.New("artifact metadata mismatch")
	ErrStateChanged     = errors.New("model state changed during update")
	ErrNoPrevious       = errors.New("no previous version to roll back to")
	ErrNoModelPath      = errors.New("state declares no model path")
	ErrNoRepo           = errors.New("no repository configured")
)

Sentinel errors for callers to match with errors.Is.

Types

type Client

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

Client is the store entry point: registry access plus local store.

func New

func New(opts Options) (*Client, error)

New validates options and builds a Client.

func (*Client) Check

func (c *Client) Check(ctx context.Context, id string) ([]Update, error)

Check compares installed models against the index; id may be empty to check everything.

func (*Client) Current

func (c *Client) Current(id string) (*State, error)

Current returns the state behind the "current" symlink.

func (*Client) Index

func (c *Client) Index(ctx context.Context) (*Index, error)

Index fetches the catalog from the registry.

func (*Client) Info

func (c *Client) Info(ctx context.Context, idOrRef string) (kf *KitFile, digest string, err error)

Info returns the KitFile of a published model and its manifest digest without touching layers.

func (*Client) Install

func (c *Client) Install(ctx context.Context, idOrRef string, progress func(Progress)) (*State, error)

Install downloads a model into root/<id>/<version> and switches "current" to it; a bare index id is pinned to the indexed digest.

func (*Client) Installed

func (c *Client) Installed() ([]*State, error)

Installed lists the current state of every installed model.

func (*Client) ModelPath

func (c *Client) ModelPath(st *State) (string, error)

ModelPath returns the verified absolute path to the weights of an installed version — the canonical way to hand a model to an engine.

func (*Client) Prune

func (c *Client) Prune(ctx context.Context, id string, keep int) ([]string, error)

Prune removes old versions, keeping the current one and the newest (keep-1) others; keep < 1 is treated as 1. It returns the removed versions.

func (*Client) Remove

func (c *Client) Remove(ctx context.Context, id, version string) error

Remove deletes one version; the current one is refused.

func (*Client) RemoveAll

func (c *Client) RemoveAll(ctx context.Context, id string) error

RemoveAll deletes a model with all its versions.

func (*Client) Rollback

func (c *Client) Rollback(ctx context.Context, id string) (*State, error)

Rollback switches "current" to the previous installed version.

func (*Client) Root

func (c *Client) Root() string

Root returns the local models directory.

func (*Client) SwitchCurrent

func (c *Client) SwitchCurrent(ctx context.Context, id, version string) error

SwitchCurrent atomically points "current" to the given version.

func (*Client) Update

func (c *Client) Update(ctx context.Context, id string, progress func(Progress)) ([]*State, error)

Update installs available index versions; an empty id updates all models. On failure it returns states completed before the error.

func (*Client) Verify

func (c *Client) Verify(id string) (*VerifyReport, error)

Verify re-hashes the files of the current version against the state.

func (*Client) Versions

func (c *Client) Versions(id string) ([]string, error)

Versions lists installed version directories of a model, sorted.

type Exedra

type Exedra struct {
	// Engine executes the model: llama, transcribe.
	Engine string `json:"engine" yaml:"engine"`
	// Caliber is the model class within its modality; ladders do not compare.
	Caliber string `json:"caliber" yaml:"caliber"`
	// Capabilities are modalities.
	Capabilities []string `json:"capabilities" yaml:"capabilities"`
	// Languages the model claims: ISO 639-1 codes or Multilingual; empty means no claim.
	Languages []string `json:"languages" yaml:"languages"`
	// Features are verified mechanics.
	Features []string `json:"features" yaml:"features"`
	// Priority ranks models competing for the same request; higher wins.
	Priority int `json:"priority" yaml:"priority,omitempty"`
	// RunArgs are extra engine arguments the model requires.
	RunArgs []string `json:"run_args,omitempty" yaml:"run_args,omitempty"`
}

Exedra is the model.parameters.exedra block; values are named in pkg/metadata.

func (Exedra) SupportsLanguage

func (e Exedra) SupportsLanguage(lang string) bool

SupportsLanguage reports whether the model claims the language.

type FileDigest

type FileDigest struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

FileDigest is one extracted file with its content hash.

type Index

type Index struct {
	Generated string       `yaml:"generated" json:"generated"`
	Registry  string       `yaml:"registry" json:"registry"`
	Namespace string       `yaml:"namespace" json:"namespace"`
	Models    []IndexEntry `yaml:"models" json:"models"`
}

Index is the exedra-index catalog.

func (*Index) Lookup

func (i *Index) Lookup(id string) (IndexEntry, bool)

Lookup finds a model by id.

type IndexEntry

type IndexEntry struct {
	ID          string   `yaml:"id" json:"id"`
	Version     string   `yaml:"version" json:"version"`
	Ref         string   `yaml:"ref" json:"ref"`
	Digest      string   `yaml:"digest" json:"digest"`
	Size        int64    `yaml:"size" json:"size"`
	Format      string   `yaml:"format" json:"format,omitempty"`
	Path        string   `yaml:"path" json:"path,omitempty"`
	Description string   `yaml:"description" json:"description,omitempty"`
	License     string   `yaml:"license" json:"license,omitempty"`
	Authors     []string `yaml:"authors" json:"authors,omitempty"`
	Exedra      Exedra   `yaml:"exedra" json:"exedra"`
}

IndexEntry describes one published model.

type KitFile

type KitFile struct {
	Package KitPackage `json:"package"`
	Model   KitModel   `json:"model"`
}

KitFile is the packed ModelKit config blob (relevant fields only).

type KitModel

type KitModel struct {
	Name       string        `json:"name"`
	Path       string        `json:"path"`
	Format     string        `json:"format"`
	License    string        `json:"license"`
	Parameters KitParameters `json:"parameters"`
}

KitModel is the model block of a KitFile.

type KitPackage

type KitPackage struct {
	Name        string   `json:"name"`
	Version     string   `json:"version"`
	Description string   `json:"description"`
	Authors     []string `json:"authors"`
}

KitPackage is the package metadata block of a KitFile.

type KitParameters

type KitParameters struct {
	Exedra Exedra `json:"exedra"`
}

KitParameters is the model.parameters block of a KitFile.

type Options

type Options struct {
	Repo      string // OCI repo prefix; optional, only bare ids and the index need it
	Root      string // local models dir
	PlainHTTP bool   // disable TLS (local debug registries)
}

Options configures a Client.

type Progress

type Progress struct {
	Model       string
	Step        ProgressStep
	Layer       string
	Size        int64
	Transferred int64
}

Progress reports one model installation step. StepDownload repeats with a growing Transferred; its last event carries Transferred == Size.

type ProgressStep

type ProgressStep int

ProgressStep identifies an installation phase.

const (
	StepDownload ProgressStep = iota + 1
	StepReuse
	StepDone
)

Installation phases reported via Progress.

type State

type State struct {
	ID      string       `json:"id"`
	Version string       `json:"version"`
	Ref     string       `json:"ref"`
	Digest  string       `json:"digest"`
	Layers  []StateLayer `json:"layers"`
	Format  string       `json:"format,omitempty"`
	// Path is the declared weights file; resolve via Client.ModelPath.
	Path        string    `json:"path,omitempty"`
	Description string    `json:"description,omitempty"`
	License     string    `json:"license,omitempty"`
	Authors     []string  `json:"authors,omitempty"`
	Exedra      Exedra    `json:"exedra"`
	InstalledAt time.Time `json:"installed_at"`
}

State records what exactly is installed in a version directory.

func (*State) ModelFiles

func (s *State) ModelFiles() []string

ModelFiles lists the files of the model (weights) layers, relative to the version directory.

func (*State) Size

func (s *State) Size() int64

Size sums the layer sizes of the installed version.

type StateLayer

type StateLayer struct {
	Digest    string       `json:"digest"`
	Size      int64        `json:"size"`
	MediaType string       `json:"media_type"`
	Files     []FileDigest `json:"files,omitempty"`
}

StateLayer is one installed layer with the files it contributed.

type Update

type Update struct {
	ID        string `json:"id"`
	Installed string `json:"installed"`
	Available string `json:"available"`
	Ref       string `json:"ref"`
	Size      int64  `json:"size"`
}

Update describes an available upgrade for an installed model.

type VerifyReport

type VerifyReport struct {
	ID       string   `json:"id"`
	Version  string   `json:"version"`
	Files    int      `json:"files"`
	Problems []string `json:"problems,omitempty"`
}

VerifyReport is the outcome of checking one installed model.

func (*VerifyReport) Intact

func (r *VerifyReport) Intact() bool

Intact reports whether every file matched its recorded hash.