Developer infrastructure for AI systems

AI model containers with a clearer execution boundary.

modelc is a CLI and specification for packaging AI models as portable, inspectable units with declared artifacts, defined interfaces, and reproducible execution.

Get the code How it works

Install

pip install modelc

Packaging: Portable .modelc.tar.gz archives
Execution: Structured JSON in, structured JSON out
Focus: Inspectability, portability, reproducibility

Why modelc

A model should be understandable before it is executed.

Most model delivery still depends on scattered files, undocumented assumptions, and ad hoc run instructions. modelc introduces a small, explicit unit of AI execution that can be built, inspected, and run consistently.

$ modelc inspect sentiment-basic.modelc.tar.gz

Name: sentiment-basic
Version: 0.1.0
Runtime: python 3.11
Entrypoint: python entrypoint/run.py

$ modelc run . --input '{"text":"I love this"}'

{
  "label": "positive",
  "confidence": 0.98
}

Portable

Package models as self-contained artifacts instead of loose collections of files and assumptions.

Inspectable

Read the structure, runtime requirements, and interface before you run anything.

Composable

Use declared interfaces as a foundation for evaluation, contracts, and larger systems.

The gap

Model delivery is still more fragile than it should be.

Even when a model is available publicly, using it often requires reconstructing an environment, identifying the right artifacts, and interpreting informal assumptions about input shape, output structure, and execution flow.

In software, containers created a cleaner boundary between code and runtime. In AI, that boundary is still weak. modelc is an attempt to define a small but useful primitive at that layer.

The manifest

A simple spec with explicit structure.

modelc uses a developer-friendly manifest that keeps the important parts visible: metadata, runtime, artifacts, interface schema, and entrypoint.

Schema versioning through apiVersion
Declared runtime requirements
Named artifacts for weights and tokenizers
Input and output schema definitions
Predictable execution entrypoint

apiVersion: modelc.dev/v0
kind: ModelContainer

metadata:
  name: sentiment-basic
  version: 0.1.0

runtime:
  type: python
  version: "3.11"

artifacts:
  weights:
    path: ./model/
    format: pytorch
  tokenizer:
    path: ./tokenizer/
    format: huggingface

interface:
  input:
    type: text
    schema:
      text: string
  output:
    type: classification
    schema:
      label: string
      confidence: float

entrypoint:
  command: python run.py

Workflow

A tighter build, inspect, and run cycle.

Describe

Use model.yaml to define the model’s structure, runtime requirements, artifacts, interface, and entrypoint.

Build

Package the project into a portable archive with a resolved manifest and a predictable internal layout.

Inspect

Read model metadata, artifacts, and schemas without executing the model first.

Run

Pass JSON through stdin, execute the entrypoint, and validate output against the declared schema.

Positioning

Not a platform. Not a framework.

modelc is meant to be a systems primitive. It defines a unit of packaging and execution that can support future layers such as evaluation, contracts, signing, provenance, and registry workflows.

The emphasis is on a disciplined v0: keep the boundary small, useful, and easy to reason about.

Roadmap

Build the primitive first. Expand carefully.

Stage

Focus

What it means

Now

Reference implementation

CLI support for build, inspect, and run using a minimal manifest and a Python execution contract.

Specification hardening

Clarify validation rules, package layout, versioning expectations, and compatibility guarantees.

Later

Trust and distribution layers

Add signing, provenance, registry workflows, and stronger integration with evaluation and contract systems.

Start here

Install the CLI and explore the reference implementation.

modelc is early, but usable. Read the code, inspect the manifest format, and follow the direction of the spec.

PyPI GitHub Spec