diff --git a/docs/src/docs/kitfile/kf-overview.md b/docs/src/docs/kitfile/kf-overview.md index 8ee4dc2c4..a29ed998c 100644 --- a/docs/src/docs/kitfile/kf-overview.md +++ b/docs/src/docs/kitfile/kf-overview.md @@ -6,32 +6,34 @@ keywords: kitfile format, kitops kitfile example, modelkit yaml, ai model manife # Kitfile Format for ModelKits -The **Kitfile** is the blueprint for every AI/ML project packaged with KitOps. +The **Kitfile** is the blueprint for every AI project packaged with KitOps. -It’s a simple, YAML-based manifest that defines what goes into a ModelKit: models, datasets, notebooks, documentation, and metadata. +It’s a simple, YAML-based manifest that defines what goes into a ModelKit: models, datasets, code, prompts, agent skill files, MCP server configurations, and documentation. ModelKits use Kitfiles to package and version your project so it can be shared, stored, or deployed from any OCI-compatible registry. -## ✨ Why Use a Kitfile? +## Why Use a Kitfile? A Kitfile helps you: -- Package your AI/ML project with full traceability +- Package your AI project with full traceability - whether it’s a model, an agent configuration, or both - Make your work reproducible across environments -- Collaborate with DevOps, ML engineers, and app developers using a shared format -- Integrate seamlessly into CI/CD pipelines and registries +- Collaborate with DevOps, ML engineers, AI engineers, and app developers using a shared format +- Integrate into CI/CD pipelines and registries -## 📚 Kitfile Sections +## Kitfile Sections Each Kitfile includes one or more of the following sections: -| Section | Description | -|---------------|-------------| -| `package` | Project metadata (name, version, license, authors) | -| `code` | Paths to notebooks or scripts | -| `model` | The serialized model and framework info | -| `datasets` | Training, validation, or other datasets | -| `docs` | Additional documentation to include | -| `prompts` | Prompt files for use with LLMs | +| Section | Description | Example contents | +|---------------|-------------|------------------| +| `package` | Project metadata (name, version, license, authors) | - | +| `model` | The serialized model and framework info | Model weights, GGUF files | +| `datasets` | Training, validation, or other datasets | CSV files, Parquet datasets | +| `code` | Code, scripts, and server configurations | Jupyter notebooks, MCP server code and config files | +| `prompts` | Prompt files and agent skill files | System prompts, SKILL.md, .cursorrules | +| `docs` | Additional documentation | README, usage guides | + +The `prompts` section is the natural home for agent skill files and prompt templates. The `code` section is where MCP server code and configuration files go. You can organize these however fits your project - the key is that everything gets versioned together. You can extract the Kitfile from any existing ModelKit: @@ -39,13 +41,13 @@ You can extract the Kitfile from any existing ModelKit: kit unpack [registry/repo:tag] --config -d . ``` -## ✅ Minimal Kitfile Example +## Minimal Kitfile Examples The only required fields are: - `manifestVersion` - At least one of `code`, `model`, `datasets`, `docs`, or `prompts` section -Example: +A ModelKit for a dataset: ```yaml manifestVersion: v1.0.0 @@ -56,12 +58,30 @@ datasets: path: ./data/test.csv ``` +A ModelKit for agent skills and prompts (no model required): +```yaml +manifestVersion: v1.0.0 + +package: + name: customer-support-agent + description: Skill files and prompts for the customer support agent + version: 2.1.0 + +prompts: + - path: ./prompts/system.prompt.md + description: System prompt for the support agent + - path: ./skills/escalation.skill.md + description: Skill for escalating tickets to human agents + - path: ./skills/refund-processing.skill.md + description: Skill for processing refund requests +``` + ### Notes on Kitfile Behavior - Kitfiles must use relative paths (not absolute) -- ModelKits can include only one model, but multiple datasets or code bases -- You can currently only build ModelKits from local files — but support for remote sources (e.g. DVC, S3) is coming soon +- ModelKits can include only one model, but multiple datasets, code entries, or prompts +- You can currently only build ModelKits from local files, but support for remote sources (e.g. DVC, S3) is coming soon -## 🧱 Example: Full Kitfile +## Example: Full Kitfile with Model ```yaml manifestVersion: v1.0.0 @@ -98,6 +118,41 @@ prompts: description: System prompt for model inference ``` +## Example: Agentic AI Kitfile + +This Kitfile packages agent skill files, prompts, and an MCP server configuration together. No model is needed when the agent uses a hosted API (e.g., Claude, GPT). + +```yaml +manifestVersion: v1.0.0 + +package: + name: sales-research-agent + description: Agent configuration for automated sales research pipeline + authors: + - Platform Team + version: 3.0.1 + +prompts: + - path: ./prompts/system-prompt.md + description: Core system prompt defining agent persona and constraints + - path: ./prompts/research-prompt.md + description: Prompt template for company research tasks + - path: ./skills/linkedin-enrichment.skill.md + description: Skill for enriching leads with LinkedIn data + - path: ./skills/competitive-analysis.skill.md + description: Skill for generating competitive analysis summaries + +code: + - path: ./mcp-servers/crm-connector + description: MCP server for CRM data access + - path: ./mcp-servers/web-scraper + description: MCP server for web scraping with rate limiting + +docs: + - path: ./README.md + description: Agent setup and deployment guide +``` + ## Learn More ➡️ Explore the [Kitfile structure](../format.md) in detail diff --git a/docs/src/docs/modelkit/intro.md b/docs/src/docs/modelkit/intro.md index 78da9d917..4c0a9a778 100644 --- a/docs/src/docs/modelkit/intro.md +++ b/docs/src/docs/modelkit/intro.md @@ -8,42 +8,44 @@ keywords: modelkit, modelkit overview, oci ai packaging, ml model registry, shar ![ModelKit](./ModelKit_chart.svg) ->**ModelKit is a standardized, OCI-compliant packaging format for AI/ML projects.** +>**ModelKit is a standardized, OCI-compliant packaging format for AI projects.** -It bundles everything your model needs — datasets, training code, config files, documentation, and the model itself — into a single shareable artifact. +It bundles the artifacts your AI project depends on - models, datasets, code, prompts, agent skill files, MCP server configurations, and documentation - into a single versioned, shareable artifact. -Use ModelKits to version, share, and deploy AI models across teams and environments using familiar DevOps tools like DockerHub, GitHub Packages, or private registries. +Despite the name, not every ModelKit contains a model. A ModelKit can package any combination of AI project artifacts. You might create a ModelKit that contains only prompts and skill files for an agentic AI system, or one that bundles an MCP server with its configuration, or a complete package with model weights, training data, prompts, and code. + +Use ModelKits to version, share, and deploy AI projects across teams and environments using familiar DevOps tools like DockerHub, GitHub Packages, or private registries. ➡️ [Get started with ModelKits](../../get-started.md) in under 15 minutes -➡️ [See how security-focused teams use ModelKits](../../use-cases.md) +➡️ [See how teams use ModelKits](../../use-cases.md) -## 🔑 Key Features +## Key Features * **OCI-compliant and tool-friendly** - Store, tag, and version ModelKits in any container registry — no custom infrastructure needed. + Store, tag, and version ModelKits in any container registry. No custom infrastructure needed. * **Selective unpacking** - Unpack only the parts you need (e.g. just the dataset or model weights) to speed up pipelines and reduce compute overhead. + Unpack only the parts you need (e.g. just the prompts, just the model weights, just the MCP config) to speed up pipelines and reduce overhead. * **No duplication for shared assets** - Reuse datasets or configs across multiple kits without bloating storage. + Reuse datasets, prompts, or configs across multiple kits without bloating storage. * **Familiar versioning and tagging** - Use registry-native tags (e.g. `:latest`, `:prod`, `:rollback`) to track model state and history. + Use registry-native tags (e.g. `:latest`, `:prod`, `:rollback`) to track project state and history. -* **Built for ML workflows** - Supports AI-specific needs like serialized model handling, reproducible training snapshots, and data lineage. +* **Built for AI workflows** + Supports models, datasets, prompts, agent skill files, MCP server configurations, and code. Handles both large binary files (model weights) and small text files (prompts, configs) in the same artifact. * **Streamlined collaboration** - Teams can pull, inspect, and repack models just like container images — making it easier to collaborate across roles and environments. + Teams can pull, inspect, and repack ModelKits just like container images, making it easier to collaborate across roles and environments. -## ⚡ Why It Matters +## Why It Matters -ModelKit simplifies the messy handoff between data scientists, engineers, and operations. It gives teams a common, versioned package that works across clouds, registries, and deployment setups — without reinventing storage or delivery. +ModelKit simplifies the messy handoff between data scientists, AI engineers, agent developers, and operations. It gives teams a common, versioned package that works across clouds, registries, and deployment setups without reinventing storage or delivery. -It’s more than a format — it’s a building block for secure, reproducible AI. +For self-hosted model teams, it’s the packaging layer that ties model weights to their training data, configuration, and documentation. For agentic AI teams, it’s the versioning system that ties prompts, skills, and MCP configs to a known-good state. For teams doing both, it’s one format that covers everything. -## 🔄 ModelPack Format Support +## ModelPack Format Support KitOps supports both **ModelKit** and **ModelPack** artifact formats: diff --git a/docs/src/docs/next-steps.md b/docs/src/docs/next-steps.md index fec5d31cc..261174a58 100644 --- a/docs/src/docs/next-steps.md +++ b/docs/src/docs/next-steps.md @@ -82,7 +82,7 @@ If you are building a ModelKit from a Hugging Face repository you can use the [k ### 2/ Generating a Kitfile From a Directory -If you have your AI/ML project artifacts in a directory structure already then the easiest way to get started is with [kit init](../cli/cli-reference/#kit-init). From the root of the directory with the AI/ML artifacts you wish to pack in the ModelKit run: +If you have your AI project artifacts in a directory structure already then the easiest way to get started is with [kit init](../cli/cli-reference/#kit-init). From the root of the directory with the artifacts you wish to pack in the ModelKit run: ```sh kit init . @@ -95,15 +95,16 @@ You can learn more about the syntax, options, and flags in our [CLI docs](../cli ### 3/ Writing Your Own Kitfile -There are five parts to a Kitfile: +There are six parts to a Kitfile: 1. The `package` section: Metadata about the ModelKit, including the author, description, and license 1. The `model` section: Information about the serialized model 1. The `datasets` section: Information on included datasets -1. The `code` section: Information about codebases related to the project, including Jupyter notebook folders +1. The `code` section: Information about codebases, scripts, and MCP server configurations +1. The `prompts` section: Prompt files, agent skill files, and other text-based AI configuration 1. The `docs` section: Information about documentation for the ModelKit -A Kitfile only needs the `package` section, plus one or more of the other sections. +A Kitfile needs a `manifestVersion` plus at least one of the other sections. The `package` section is recommended for metadata but not strictly required. Not every ModelKit needs a model - you can create ModelKits that contain only prompts and skill files, or only code and MCP server configurations. The `model` section can contain a single model, or you can create model dependencies with `model parts` which is covered in the [KitFile format documentation](../kitfile/format/#model). diff --git a/docs/src/docs/overview.md b/docs/src/docs/overview.md index b0c087778..24ba074a6 100644 --- a/docs/src/docs/overview.md +++ b/docs/src/docs/overview.md @@ -6,43 +6,41 @@ keywords: kitops, what is kitops, modelkit, modelpack, ai model packaging, machi # What is KitOps? -KitOps is an open-source tool that helps teams securely package, version, and deploy AI/ML models using familiar DevOps practices. +KitOps is an open-source tool for packaging, versioning, and sharing AI projects. It handles models, datasets, prompts, agent skill files, MCP server configurations, and code - bundling them into a single versioned OCI artifact that lives in your existing container registry. -It’s built for data scientists, developers, and platform engineers working together on self-hosted AI/ML models — and it makes sharing, automating, and deploying those models as simple as managing containerized apps. +Whether you’re deploying self-hosted models, building agentic AI systems, or managing prompt and skill libraries across teams, KitOps gives you one standard way to package, version, and distribute every artifact your AI project depends on. -Just like PDFs standardized document sharing, KitOps standardizes how AI/ML projects are packaged, shared, and deployed. - -It’s a format your tools can understand, your teams can trust, and your pipelines can automate. +Just like PDFs standardized document sharing, KitOps standardizes how AI projects are packaged, shared, and deployed. It’s a format your tools can understand, your teams can trust, and your pipelines can automate. ## Why Use KitOps? -AI/ML models are more than code. They include model weights, datasets, configuration files, prompts, and documentation. Most teams store these assets in separate, disconnected repositories. This creates security gaps and breaks traceability between models, training data, and source notebooks. +AI projects are more than code. A self-hosted model needs weights, datasets, configuration files, and documentation. An agentic AI system adds prompts, skill files, and MCP server configurations to that list. Most teams store these assets in separate, disconnected places - Git for code, object storage for weights, hardcoded strings for prompts, scattered config files for MCP servers. This creates security gaps, breaks traceability, and makes it impossible to reproduce a known-good state. -KitOps packages everything your model needs for development or production in a single versioned OCI Artifact that you store in your container registry. +KitOps packages everything your AI project needs into a single versioned OCI artifact stored in your container registry. When something breaks in production, you can answer: what exact combination of model, prompts, skills, and configs was running? You can: -- Package models into deployable artifacts -- Share datasets and code securely between teams +- Package models, prompts, skills, MCP configs, and datasets into versioned artifacts +- Share complete AI project snapshots securely between teams - Automate packaging and deployment in CI/CD pipelines -- Run or test a model anywhere — without fragile setup steps +- Reproduce any previous state by pulling a specific version ➡️ [Get started](../get-started.md) in minutes ## What’s Included -### 🎁 ModelKit: Standardized Model Packaging +### ModelKit: Standardized AI Project Packaging -The KitOps ModelKit is a packaging format that bundles all the artifacts of your AI/ML project — including datasets, code, configs, prompts, documentation, and the model itself — into an OCI-compliant Artifact. +A ModelKit is an OCI-compliant artifact that bundles everything your AI project needs: models, datasets, code, prompts, agent skill files, MCP server configurations, and documentation. ModelKits work with any container registry and can be managed just like container images. -This means ModelKits can be stored in your existing image registry, deployed to Kubernetes (or anywhere else containers run), and managed just like any container image. +Not every ModelKit contains a model. A ModelKit might package a set of agent skills and their associated prompts, or an MCP server with its configuration. The format is flexible enough to handle any combination of AI project artifacts. -**ModelPack Support:** KitOps can also create ModelPack-compliant packages using the [CNCF model-spec format](https://github.com/modelpack/model-spec). Both ModelPack and ModelKits are vendor-neutral standards for packaging everything needed for an AI/ML project. Kit commands (pull, push, unpack, inspect, list) work transparently with both formats. +**ModelPack Support:** KitOps can also create ModelPack-compliant packages using the [CNCF model-spec format](https://github.com/modelpack/model-spec). Both ModelPack and ModelKits are vendor-neutral standards for packaging AI projects. Kit commands (pull, push, unpack, inspect, list) work transparently with both formats. See how to [deploy ModelKits](../deploy.md) -### 📄 Kitfile: Config Made Easy +### Kitfile: Define What Gets Packaged -The Kitfile is a YAML configuration that describes what goes into a KitOps ModelKit. It defines all components of your AI/ML project including models, datasets, code, prompts, and documentation. It’s designed for clarity and security — making it easy to track what’s included, and to share AI/ML projects across environments and teams. +The Kitfile is a YAML manifest that describes what goes into a ModelKit. It defines the components of your AI project - models, datasets, code (including MCP server configurations), prompts (including agent skill files), and documentation. It’s designed for clarity and security, making it easy to track what’s included and share projects across environments and teams. **Using ModelPack format:** To pack in ModelPack format instead of ModelKit format, add the `--use-model-pack` flag: @@ -52,7 +50,7 @@ kit pack . --use-model-pack -t myregistry/mymodel:latest When packing as ModelPack, KitOps stores your Kitfile as a manifest annotation so you can still retrieve it later. Commands like `kit unpack`, `kit pull`, and `kit inspect` work the same way regardless of format. -### 🖥️ Kit CLI: Create, Run, Automate +### Kit CLI: Create, Run, Automate The Kit CLI is the command-line tool that ties everything together. Use it to: - Create ModelKits from your local project @@ -62,30 +60,39 @@ The Kit CLI is the command-line tool that ties everything together. Use it to: ## Who Uses KitOps? -KitOps helps bridge the gap between experimentation and production for AI/ML workflows. Whether you’re running in the cloud, on-prem, or at the edge, KitOps makes it easier to collaborate across roles: +KitOps helps bridge the gap between experimentation and production for AI workflows. Whether you’re running in the cloud, on-prem, or at the edge, KitOps makes it easier to collaborate across roles: ### For DevOps & Platform Engineers - Use ModelKits in existing automation pipelines -- Store and manage models in your current container registry -- Build golden paths for secure AI/ML deployment +- Store and manage AI artifacts in your current container registry +- Build golden paths for secure AI deployment - models, agents, and MCP servers +- Gate promotions with signing and attestation workflows ➡️ Integrate with [CI/CD](../integrations/cicd.md) ➡️ Add KitOps to [experiment trackers](../integrations/mlflow.md) -➡️ [Build a better golden path](../use-cases/) for AI/ML projects. +➡️ [Build a better golden path](../use-cases/) for AI projects. ### For Data Scientists - Package datasets and models without infrastructure hassle - Share your work with developers without “it works on my machine” issues - Keep code and data versions aligned -📺 [See how to use KitOps with Jupyter Notebooks](https://www.youtube.com/watch?v=OQPp7QEvk7Q). +[See how to use KitOps with Jupyter Notebooks](https://www.youtube.com/watch?v=OQPp7QEvk7Q). ➡️ Use the [PyKitOps Python SDK in your notebooks](../pykitops/index.md) +### For AI Engineers & Agent Developers +- Version prompts, skill files, and MCP server configs alongside your code +- Lock down reproducible agent state: exact prompt version + model version + skill version +- Share tested agent configurations across teams without copy-paste drift +- Pull only the artifacts you need (e.g., just the prompts) without downloading the full package + +➡️ [Get started](../get-started.md) + ### For Developers -- Use AI/ML models like any dependency — no deep ML knowledge required +- Use AI models and agent artifacts like any dependency - Drop into apps using standard tools and APIs - Let your team innovate without breaking your pipeline @@ -93,7 +100,7 @@ KitOps helps bridge the gap between experimentation and production for AI/ML wor ## A Standards-Based Approach -The goal of KitOps is to become the open, vendor-neutral standard that simplifies and secures the packaging and versioning of AI/ML projects. In the same way that PDFs have helped people share documents, images, and diagrams between tools, KitOps makes it easy for teams to use the tools they prefer, but share the results safely and securely. +The goal of KitOps is to become the open, vendor-neutral standard that simplifies and secures the packaging and versioning of AI projects - from self-hosted models to agentic AI systems. In the same way that PDFs helped people share documents between tools, KitOps makes it easy for teams to use the tools they prefer but share the results safely and securely. KitOps is governed by the CNCF and supported by contributors from across the AI and DevOps ecosystem. diff --git a/docs/src/docs/security.md b/docs/src/docs/security.md index 56dab960e..40469db13 100644 --- a/docs/src/docs/security.md +++ b/docs/src/docs/security.md @@ -4,33 +4,31 @@ description: Learn how KitOps ModelKits ensure AI/ML model integrity with built- keywords: modelkit security, modelpack, ai model integrity, verify model artifact, cosign signing ml, oci security mlops, secure ai packaging, reproducible ml deployment, transparency logs, digests sha256, rekor --- -# Securing Your Model Supply Chain with KitOps +# Securing Your AI Supply Chain with KitOps -Model integrity matters. KitOps helps you protect your AI/ML project assets from corruption, tampering, or unauthorized changes — without requiring custom security code or complex setup. +AI artifact integrity matters - and it’s not just about models anymore. Prompts, agent skill files, and MCP server configurations are all attack surfaces. A tampered prompt can change agent behavior without touching a single line of code. A compromised MCP server config can route tool calls to an attacker’s endpoint. KitOps helps you protect all of these assets from corruption, tampering, or unauthorized changes. -Whether you're building models for production, working in a regulated industry, or want to enforce trust boundaries between teams, KitOps provides built-in verification and open standards for secure packaging. +Whether you’re deploying self-hosted models, managing agentic AI systems, or distributing MCP server configurations, KitOps provides built-in verification and open standards for secure packaging. ## Why Use OCI Artifacts for AI Security? OCI (Open Container Initiative) artifacts are content-addressed and immutable, which means: -- Once a ModelKit is packaged and pushed, its contents can’t silently change — every file is hashed and referenced by digest. -- The ModelKit is tamper-evident: if any model file, dataset, or config is altered, the digest no longer matches and unpacking will fail. -- OCI registries already support access control, logging, and redundancy, which gives you security without building new infrastructure. +- Once a ModelKit is packaged and pushed, its contents can’t silently change. Every file - model weights, prompts, skill files, MCP configs - is hashed and referenced by digest. +- The ModelKit is tamper-evident: if any artifact is altered, the digest no longer matches and unpacking will fail. +- OCI registries already support access control, logging, and redundancy, giving you security without building new infrastructure. -This gives KitOps a strong security foundation out-of-the-box — just like container images, but for full AI/ML projects. - -And KitOps fits seamlessly into a broader enterprise security processes and tools... +This gives KitOps a strong security foundation out of the box, for models, agent configurations, and everything in between. ## Built-in Integrity Checks Every time you run `kit unpack` or `kit pull` KitOps automatically: -1. Reads the OCI manifest for the ModelKit -2. Computes the SHA-256 digest of each layer (datasets, weights, code, Kitfile, etc.) -3. Compares each digest to the expected value from the manifest +1. Reads the OCI manifest for the ModelKit +2. Computes the SHA-256 digest of each layer (model weights, datasets, prompts, skill files, code, MCP configs, Kitfile, etc.) +3. Compares each digest to the expected value from the manifest -If any artifact has been modified — even by one byte — unpacking fails with a clear digest mismatch error. +If any artifact has been modified - even by one byte - unpacking fails with a clear digest mismatch error. This applies equally to a model weight file and a system prompt. You get the same tamper-evident guarantee for every artifact in the ModelKit. -> Zero-lift for you: You don’t need to write or manage any checksum code. This is handled automatically by the KitOps CLI and PyKitOps SDK. +> You don’t need to write or manage any checksum code. This is handled automatically by the KitOps CLI and PyKitOps SDK. ## Signing with Cosign @@ -56,6 +54,16 @@ Cosign supports OIDC-based keyless signing, eliminating key file management. Sig Combine KitOps + Cosign in [any pipeline](../integrations/cicd.md) with KitOps - that's the easiest and safest way to keep things signed and secure. +## Why This Matters for Agentic AI + +Agent security isn’t just about the model. When your agent’s behavior is defined by a combination of model + prompts + skills + MCP server configs, you need integrity guarantees across all of them. A few scenarios: + +- A prompt change that removes safety guardrails should be caught before deployment, not after an incident. +- An MCP server config that redirects tool calls to an untrusted endpoint should fail verification. +- A skill file modified outside your approved workflow should be detectable. + +By packaging all of these artifacts into a signed ModelKit, you get one verification step that covers the entire agent configuration. If anything changed, the signature breaks. + ## Audit Trails & Chain of Custody KitOps doesn’t maintain audit logs itself because it can leverage the specialty products available in the open source ecosystem. Combine KitOps with these components for full traceability: @@ -69,11 +77,12 @@ KitOps doesn’t maintain audit logs itself because it can leverage the specialt For organizations needing detailed, queryable audit history, [Jozu Hub](https://jozu.com/) (the commercial platform backing KitOps) provides: - Kubernetes-hosted installation behind the firewall -- Security scanning of all models +- Security scanning of all AI artifacts - models, agents, and MCP servers - Signed attestations for security reports attached to ModelKits - Integration with Open Policy Agent - Auto-generated secure containers and Kubernetes deployments - UI and API access to historical metadata +- MCP Registry API for centrally curated, security-scanned MCP servers ## Learn More or Get Help - [KitOps CLI](../cli/cli-reference.md) Reference diff --git a/docs/src/docs/use-cases.md b/docs/src/docs/use-cases.md index 572e80f4f..616cee1cf 100644 --- a/docs/src/docs/use-cases.md +++ b/docs/src/docs/use-cases.md @@ -4,18 +4,21 @@ description: Learn how organizations use KitOps to securely package, track, and keywords: kitops use cases, modelpack, ai model deployment workflow, mlops handoff, versioning ai models, secure ai pipelines, eu ai act compliance, ai model governance, mlflow handoff, reproducible ml deployment --- -# How Teams Use KitOps 🛠️ +# How Teams Use KitOps -KitOps helps organizations package, share, and deploy AI/ML models securely and reproducibly — using the same tools they already use for containers. +KitOps helps organizations package, share, and deploy AI projects securely and reproducibly - using the same tools they already use for containers. Teams around the world are using KitOps for: - Reproducible handoff from development to production +- Versioning agent configurations, prompts, and skills alongside models - Security and compliance (including EU AI Act, NIST AI, ISO 42001) -- Organizing all model versions in one standard system +- Organizing AI project artifacts in one standard system ➡️ See [compatible tools](../integrations/integrations.md) -## Level 1: Production Handoff +## Self-Hosted Model Deployment + +### Level 1: Production Handoff > Use Case: Reproducible, secure model handoff across teams using CI/CD @@ -25,28 +28,28 @@ Most teams start by using KitOps to version a model when it’s ready for stagin - App integration testing - Secure, consistent model handoffs across teams -Organizations that are self-hosting models ❤️ KitOps because it: +Organizations that are self-hosting models use KitOps because it: - Prevents unknown models from entering production - Enforces licensing and provenance checks (e.g. for Hugging Face imports) - Keeps datasets, model, and code synced and trackable -### In Practice +#### In Practice CI/CD pipelines using GitHub Actions, Dagger, or other systems can: -1. Pull models or data -2. Run compliance / security tests -3. Package project artifacts as a signed, versioned ModelKit -4. Push the ModelKit to a private OCI registry +1. Pull models or data +2. Run compliance / security tests +3. Package project artifacts as a signed, versioned ModelKit +4. Push the ModelKit to a private OCI registry ➡️ See [how CI/CD with KitOps works](../integrations/cicd.md) -## Level 2: Model Security +### Level 2: Model Security > Use Case: Scan and gate models during development or before release Teams working in regulated industries or secure environments use KitOps to enforce security and integrity before a model is accepted into production. -### In Practice +#### In Practice 1. Build a ModelKit for each experiment run in [MLFlow](../integrations/mlflow.md) / Weights & Biases 1. Sign the ModelKit @@ -55,20 +58,20 @@ Teams working in regulated industries or secure environments use KitOps to enfor 1. Only allow signed and attested ModelKits to move into forward environments 1. Track which model passed, which failed, and prevent risky surprises -Even when using other tools (MLFlow, Hugging Face, notebooks), KitOps provides a reliable security and auditing layer that protects environments from unsecure, or mistaken deployments. +Even when using other tools (MLFlow, Hugging Face, notebooks), KitOps provides a reliable security and auditing layer that protects environments from unsecure or mistaken deployments. -## Level 3: Versioning Everything +### Level 3: Versioning Everything > Use Case: Full model, code, and dataset lifecycle tracking -Mature teams — especially those under compliance scrutiny — extend KitOps to development. Every milestone (new dataset, tuning checkpoint, retraining event) is stored as a versioned ModelKit. +Mature teams - especially those under compliance scrutiny - extend KitOps to development. Every milestone (new dataset, tuning checkpoint, retraining event) is stored as a versioned ModelKit. Benefits: - One standard system (OCI) for every model version - Tamper-evident and content-addressable storage - Eliminates confusion over which assets belong together -### In Practice +#### In Practice 1. Build a set of approved ModelKits by [importing from Hugging Face](../hf-import.md) or adding your own internal artifacts 1. Push ModelKits to your OCI registry @@ -77,6 +80,48 @@ Benefits: 1. Perform signing, security testing and attestations as projects progress 1. Enforce policies using [OPA](https://www.openpolicyagent.org/) or similar technologies +## Agentic AI and Prompt Management + +### Versioning Prompts, Skills, and Agent Configurations + +> Use Case: Lock down agent state so every execution is reproducible + +Agentic AI systems depend on more than just the model. The prompts, skill files, and MCP server configurations that shape agent behavior change frequently and have as much impact on outcomes as the model itself. When an agent breaks in production, the first question is: what changed? Without versioned artifacts, that question is hard to answer. + +KitOps solves this by packaging prompts, skill files, and agent configurations into versioned, immutable ModelKits. Each ModelKit captures the exact state of an agent’s dependencies at a point in time. You can diff two versions to see what changed, roll back to a known-good state, and promote tested configurations through environments. + +#### In Practice + +1. Store your system prompts, agent skill files (e.g., SKILL.md, .cursorrules), and configuration in a project directory +1. Write a Kitfile that references them (skills and prompts go in the `prompts` section; MCP server configs go in the `code` section) +1. Run `kit pack` to create a versioned ModelKit +1. Push to your OCI registry with a meaningful tag (e.g., `:staging`, `:prod-2026-03-15`) +1. In your deployment pipeline, `kit pull` the exact version you need +1. When something breaks, diff the current version against the last known-good version + +This works whether your agents use Claude, GPT, Llama, or any other model. The agent framework handles orchestration; KitOps handles the packaging and versioning of everything that defines agent behavior. + +### MCP Server Configuration Management + +> Use Case: Version and distribute MCP server configurations across environments + +MCP (Model Context Protocol) servers give agents access to tools and data sources. As your MCP server inventory grows, managing configurations across development, staging, and production becomes its own problem. + +KitOps lets you package MCP server code and configurations as ModelKits. Each environment pulls the exact MCP configuration it needs from the registry. Changes to MCP configs go through the same version, sign, scan, promote workflow as any other artifact. + +#### In Practice + +1. Package your MCP server code and config files in a ModelKit using the `code` section of the Kitfile +1. Tag versions by environment (`:dev`, `:staging`, `:prod`) +1. Use `kit unpack --filter=code` to extract only the MCP configuration when deploying +1. Sign the ModelKit so downstream consumers can verify the MCP server hasn’t been tampered with + +### Combining Models and Agent Artifacts + +> Use Case: Ship a complete, self-contained AI system as one artifact + +For teams running self-hosted models inside agentic systems, KitOps can package everything in a single ModelKit: the model weights, the prompts that shape its behavior, the skill files that define agent capabilities, the MCP server configurations, and the datasets used for evaluation. One artifact, one version, one source of truth. + ➡️ [Get started](../get-started.md) with KitOps in your team. --- diff --git a/docs/src/docs/why-kitops.md b/docs/src/docs/why-kitops.md index c1e43f898..43241d724 100644 --- a/docs/src/docs/why-kitops.md +++ b/docs/src/docs/why-kitops.md @@ -6,37 +6,40 @@ keywords: kitops, modelkit, modelpack, ml model versioning, ai packaging, ai ml # Why Use KitOps? -AI/ML projects are complex. KitOps makes them manageable. +AI projects are complex. KitOps makes them manageable. -From datasets and models to configuration and deployment artifacts, every AI/ML project has many moving parts — and no consistent way to version, package, or deploy them together. KitOps solves this with an open-source, OCI-based standard for packaging and sharing complete AI/ML projects. +Every AI project has many moving parts - models, datasets, prompts, agent skill files, MCP server configurations, code, and documentation. There's no consistent way to version, package, or deploy them together. KitOps solves this with an open-source, OCI-based standard for packaging and sharing complete AI projects. -## The Problem: No Standard Way to Package AI/ML Projects +## The Problem: No Standard Way to Package AI Projects -Most AI/ML projects are scattered across tools: +AI project artifacts are scattered across tools: - Code in Jupyter notebooks or Git -- Datasets in S3 buckets or DVC -- Configs hidden in pipelines or feature stores -- Pipelines in proprietary systems +- Model weights in S3 buckets or model hubs +- Datasets in object storage or DVC +- Prompts hardcoded in application code or lost in Slack threads +- Agent skill files copy-pasted between repos +- MCP server configs managed ad-hoc per environment +- Pipeline configs hidden in proprietary systems -Each has its own package and its own version - but nothing ties the whole project together, and getting the wrong combination means delays, risk, and failure. +Each has its own versioning (if any) and its own storage. Nothing ties the whole project together. Getting the wrong combination means delays, risk, and failure. -This makes it hard to answer critical questions like: +This makes it hard to answer critical questions: - What code and data was used to train this model? -- Who built and approved it? -- What version is running in production? -- What changed — and when? +- Which prompt version is running in production? +- What changed between the working agent and the broken one? +- Who built and approved it, and when? It also slows down collaboration between teams and introduces risks for security, compliance, and reproducibility. ## The KitOps Solution -KitOps brings DevOps-style packaging to AI/ML workflows. +KitOps brings DevOps-style packaging to AI workflows - for both self-hosted models and agentic AI systems. Using KitOps, you can: -- Package model, code, datasets, metadata — into a single, versioned ModelKit +- Package models, prompts, skill files, MCP configs, datasets, and code into a single, versioned ModelKit - Store and share using any OCI-compliant registry (Docker Hub, GitLab, Harbor) -- Unpack only what you need (e.g., just code, just dataset) -- Run reproducible pipelines across development, testing, and production +- Unpack only what you need (e.g., just the prompts, just the model) +- Reproduce any previous state across development, testing, and production - Reduce risk with immutable, traceable AI project artifacts KitOps is designed for speed, security, and interoperability. @@ -58,8 +61,8 @@ Built with standards from the Open Container Initiative (OCI), KitOps is compati KitOps has been downloaded by hundreds of thousands of users, and is in production use in high security organizations, governments, enterprises, and clouds. Teams use it to: -1. Create a central source of truth for models and datasets -1. Speed up model deployment with standardized artifacts +1. Create a central source of truth for AI project artifacts - models, prompts, skills, configs, and datasets +1. Speed up deployment with standardized, versioned artifacts 1. Track changes and approvals for compliance and audits 1. Enforce consistency across environments @@ -68,19 +71,20 @@ Teams use it to: ## KitOps Helps You Answer: - What data trained this model? -- Which version is deployed where? -- Who signed off on it — and when? -- What changed between model version 3 and 4? +- Which prompt version is deployed in production? +- What exact combination of model + prompts + skills was running when the agent broke? +- Who signed off on it, and when? +- What changed between version 3 and version 4? ➡️ See how [security is built-in](../security.md) ## How KitOps Compares -KitOps doesn’t replace your favorite AI/ML tools — it complements them with the secure, standardized packaging they are missing. +KitOps doesn’t replace your favorite AI tools - it complements them with the secure, standardized packaging they are missing. ### KitOps and MLOps Platforms -Tools like MLflow, Weights & Biases, and others are great for tracking experiments. But they aren’t designed to package and version full AI/ML projects for handoff across teams or deployment pipelines. +Tools like MLflow, Weights & Biases, and others are great for tracking experiments. But they aren’t designed to package and version full AI projects for handoff across teams or deployment pipelines. KitOps: - Creates secure, immutable packages @@ -90,6 +94,16 @@ KitOps: ➡️ Integrate [KitOps with experiment trackers](../integrations/mlflow.md) +### KitOps and Agentic AI Frameworks + +Agent frameworks like LangChain, CrewAI, as well as models like Claude can handle agentic orchestration and execution. But they don’t solve the packaging and versioning problem: which prompts, skills, and MCP server configs were running when the agent worked correctly? + +KitOps: +- Versions prompts, skill files, and MCP configs as immutable artifacts +- Ties the exact prompt version to the exact model version and skill set +- Lets you roll back to a known-good agent configuration with one command +- Makes agent state reproducible across environments + ### KitOps and Jupyter Notebooks Notebooks are great for prototyping, but poor at versioning and reproducibility. @@ -99,13 +113,13 @@ ModelKits: - Preserve state outside the notebook - Let others reuse your work without opening a notebook -👉 Tip: Add a Kitfile to your notebook project and run `kit pack` at the end of each run. +Tip: Add a Kitfile to your notebook project and run `kit pack` at the end of each run. ➡️ Add [KitOps to your notebook](https://www.youtube.com/watch?v=OQPp7QEvk7Q) ### KitOps and Containers -Containers are ideal for deployment — but they’re awkward for tracking datasets, configs, or experiment metadata. +Containers are ideal for deployment, but they’re awkward for tracking datasets, configs, or experiment metadata. ModelKits: - Can include Dockerfiles and container artifacts @@ -117,28 +131,28 @@ ModelKits: ### KitOps and Git -Git is built for code — not large binary files like models or datasets. +Git is built for code, not large binary files like models or datasets. ModelKits: - Handle binaries gracefully (no LFS nightmares) -- Keep everything in sync +- Keep everything in sync - model weights, prompts, skills, configs, and code - Can still include code snapshots from Git when needed -### KitOps and Ad-Hoc Dataset Storage +### KitOps and Ad-Hoc Storage -Datasets are often scattered across S3 buckets, local drives, databases, or BI tools. That makes it hard to answer questions like: +AI project artifacts are often scattered across S3 buckets, local drives, config management tools, and hardcoded strings. That makes it hard to answer questions like: - Which model used this dataset? -- Did this dataset change — and when? -- Is this data safe to use? +- Which prompt version was running when the agent failed? +- Is this MCP server config safe to deploy? ModelKits: -- Version datasets alongside model code and configs +- Version all project artifacts together - datasets, prompts, skills, configs, and code - Reduce duplication and risk - Support reproducibility and audit trails ### Recap: What Makes KitOps Unique -1. Full AI/ML project packaging +1. Full AI project packaging - models, prompts, skills, MCP configs, datasets, and code 1. Built on OCI standards 1. Works with your existing registries and CI/CD 1. Open source, vendor-neutral