Skip to content

Improve support for model-spec format; add support for raw layers and zstd compression#1202

Open
amisevsk wants to merge 12 commits into
kitops-ml:mainfrom
amisevsk:modelpack-support-improvements
Open

Improve support for model-spec format; add support for raw layers and zstd compression#1202
amisevsk wants to merge 12 commits into
kitops-ml:mainfrom
amisevsk:modelpack-support-improvements

Conversation

@amisevsk

@amisevsk amisevsk commented Jun 3, 2026

Copy link
Copy Markdown
Contributor

Description

Improve support for model-spec formatted artifacts in KitOps. Our goal is to support any valid ModelPack transparently within KitOps; as a result this PR adds support for raw layer types (i.e. non-tar) and zstd compression as specified by the model-spec mediatypes.

  • Kitfile generation for ModelPacks that do not contain a Kitfile is improved:
    • LayerInfo (digest and diffId) are populated in the generated Kitfile. DiffIds are only included if the model config is available (e.g. in library usage, a config may not be available/desirable)
    • When we generate a Kitfile for a ModelPack, we now read the model config to get DiffIDs.
    • Kitfiles for ModelPacks that contain multiple model.weight layers are now properly generated -- additional model.weight layers are included in modelparts within the Kitfile
  • ModelPacks with multiple weight layers are now handled correctly in unpack operations. Even though Kitfiles only support one "model" and N "modelparts"
  • Unpacking in general has been refactored and simplified -- the old process is moved into a legacy.go file (as it is required for ModelKits created pre KitOps v0.5.0 when we added LayerInfo) and the new process uses LayerInfo and is more extensively tested.
  • kit pack now supports zstd compression and raw layers:
    • Raw layers are supported by a new flag: --layer-format with options tar (default) and raw (no tar wrapper)
    • Compression is supported by an additional zstd option on the existing --compression flag
  • kit unpack also now supports zstd compression and raw layers, transparently.
  • In addition to significant unit testing additions, functional tests have been updated to verify behaviour across all valid configurations of compression, layer format, and model format (ModelKit vs ModelPack)
    • For raw layer-format artifacts, tests also not ensure that layer diffID (or digest in the no compression case) is the actual file's sha256sum

I've tried to keep the Git commit history useful for this one, as there are a lot of changes here. Each commit should be self-contained and include a meaningful description of the changes within

Linked issues

N/A, forgot to create one

AI-Assisted Code

  • This PR contains AI-generated code that I have reviewed and tested (mostly test cases for this one)
  • I take full responsibility for all code in this PR, regardless of how it was created

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@gorkem

gorkem commented Jun 4, 2026

Copy link
Copy Markdown
Member

@amisevsk Other than the CI failure this looks OK

@amisevsk

Copy link
Copy Markdown
Contributor Author

Odd, the sources are well-formatted on my end

amisevsk added 10 commits June 15, 2026 17:56
Fix issues around generating Kitfiles for ModelPacks that do not have
the Kitfile annotation (i.e. were not generated by Kit originally):

* Add layerinfo (digest and diffID) to generated Kitfile, as this is
  potentially required in other tools
  * DiffIDs depend on an optional ModelPack config object being passed
    in and are omitted if the object is nil
* Retrieve ModelPack config when generating a Kitfile in our code to
  ensure DiffIDs are included.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Kit-generated artifacts (both ModelKits and ModelPacks) have at most one
"main" model layer -- i.e. layers with mediatype

  * application/vnd.kitops.modelkit.model.v1.tar (ModelKit)
  * application/vnd.cncf.model.weight.v1.tar (CNCF ModelPack)

However, ModelPacks in general may have N model.weight layers, which is
not representable in a Kitfile. To accommodate this, Kit generates a
Kitfile for ModelPack artifacts that places additional model.weight
layers within the modelparts section (as it would during normal kit
init).

When unpacking, we need to account for this by checking the Kitfile's
modelparts for additional model.weight layers encountered after the
first one; otherwise, we unpack additional weight layers to the
incorrect path

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
The unpackRecursive function is very long and touches disk, making it
hard to write test cases for its behavior, which has become rather
complicated. To enable writing tests for key functionality, split the
function into testable parts where possible.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
…odel-spec

* Update KitOps mediatype handling to support raw-formatted layers (i.e.
  non-tar) and zstd compression, to bring it in line with model-spec.
* Fix filepath annotation handling on Windows by normalizing to
  unix-style paths.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
* Add support for the raw mediatype from model-spec by writing layer
  contents directly to the file specified by the model-spec filepath
  annotation
* Add support for zstd compression in unpacking.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Add support for packing raw layers in addition to tar layers. Raw layers
are saved directly.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Signed-off-by: Angel Misevski <amisevsk@gmail.com>
ModelPacks do not support compression with raw layers; since raw layers
are now generally supported by KitOps, we need to validate that the
ModelPacks we generate are valid.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Add tests to ensure that layers packed in raw format contain DiffIDs
that match the actual SHA256 sum of the file being packed. This is
useful for tracking provenance (e.g. you know the digest of the file and
want to find ModelKits that contain that file).

For the no-compression case, we also assert that the layer digest
matches.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
@amisevsk amisevsk force-pushed the modelpack-support-improvements branch from 1eac8c7 to 5318d4c Compare June 15, 2026 21:56
@amisevsk

Copy link
Copy Markdown
Contributor Author

This is fun... MacOS and Linux disagree on go fmt:

diff --git a/testing/pack-unpack_test.go b/testing/pack-unpack_test.go
index d11b873..0d85bee 100644
--- a/testing/pack-unpack_test.go
+++ b/testing/pack-unpack_test.go
@@ -205,9 +205,9 @@ func TestPackReproducibility(t *testing.T) {
                {"--layer-format", "raw"}, // raw format
                {"--compression", "gzip"}, // tar + gzip
                {"--layer-format", "raw", "--compression", "gzip"}, // raw + gzip
-               {"--use-model-pack"},                               // modelpack default
-               {"--use-model-pack", "--layer-format", "raw"},      // modelpack + raw format
-               {"--use-model-pack", "--compression", "gzip"},      // modelpack + tar + gzip
+               {"--use-model-pack"},                          // modelpack default
+               {"--use-model-pack", "--layer-format", "raw"}, // modelpack + raw format
+               {"--use-model-pack", "--compression", "gzip"}, // modelpack + tar + gzip
        }

        testKitfile := `

amisevsk added 2 commits June 15, 2026 18:36
Test ModelPack usage in pack-unpack scenarios in functional tests in
addition to ModelKits.

Signed-off-by: Angel Misevski <amisevsk@gmail.com>
Signed-off-by: Angel Misevski <amisevsk@gmail.com>
@amisevsk amisevsk force-pushed the modelpack-support-improvements branch from 5318d4c to e4af498 Compare June 15, 2026 22:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants