AI Packages

AI Core installs .aip packages. A package can be a Wasm plugin with explicit actions, a code-free pipeline package, or a mixed package that ships actions plus bundled pipeline files.

Package authors use the aip-pack tool binary to turn a package directory into one installable .aip artifact. Runtime hosts install the resulting bytes into AI Core through FFI, Rust, or the process boundary.

Tool Artifacts

• aip-pack: normal marketplace package flow. It creates encrypted packages and includes Marketplace operator commands.
• aip-pack-for-developers: local developer package flow. It creates plaintext developer-signed packages for debugging.
• aip-pack-no-marketplace: controlled local, enterprise, or white-label package flow. It can create plaintext packages without Marketplace license checks, with optional developer signing.

SDK users should receive these as released tool binaries. They should not need to build the tool from the source repository.

Example Packages

The AI Core site provides downloadable reference packages for the common plugin shapes:

• Pipeline package: a code-free package built from pipeline.json, skills/, and schemas/. Use it when the plugin is mostly prompt and pipeline orchestration. AI Core exposes the default run_pipeline action for this shape.
• Wasm action package: a Rust/Wasm package with explicit actions, model slots, config schema metadata, and Wasm ABI exports. Use it when the plugin needs custom validation, private logic, external tool calls, or typed action handlers.

Each example includes its own README, aip.template.json, package files, and commands for packaging it into a .aip artifact. Start from the example that matches your plugin shape, then replace ids, schemas, skills, model slots, requirements, and output contracts with your own product contract.

Package Directory

A package directory usually contains:

• aip.template.json: package manifest template;
• pipeline.json: code-free pipeline definition, when the package is a pipeline package;
• skills/: markdown instructions or prompt material used by pipeline steps;
• schemas/: JSON schemas, examples, or output contracts;
• wasm/ or another declared entrypoint file, when the package exposes Wasm actions.

A package directory is scanned automatically from the root. Keep package assets in that root tree and avoid leaving unrelated repo files there. The tool will skip some common source and build artifacts, but it still only packages what it finds under the package root.

Templates contain manifest payload fields only. Do not add generated schema, issuer, signatures, Marketplace approval data, encrypted envelopes, or generated files[] hashes by hand.

Minimal Pipeline Package

aip.template.json declares identity, version, requirements, model slots, config schema, and which files belong to the package:

{
  "kind": "pipeline",
  "plugin": {
    "id": "example_pipeline",
    "version": "0.1.0"
  },
  "requirements": {
    "core": "^0.1.0",
    "plugin_api": "^0.1.0"
  },
  "entrypoint": {
    "pipeline": "pipeline.json"
  },
  "model_slots": [
    {
      "id": "draft",
      "description": "Writes the first draft",
      "fallback": "core.default"
    }
  ],
  "config": {
    "public_schema": "schemas/public-config.schema.json",
    "secrets_schema": "schemas/secrets.schema.json"
  }
}

pipeline.json describes the steps AI Core will run:

{
  "schema": "ai_core.pipeline.v1",
  "id": "example_pipeline.run",
  "input": {
    "schema": "example_pipeline.request.input.v1",
    "required": ["topic"]
  },
  "steps": [
    {
      "id": "draft",
      "model_slot": "draft",
      "skill": "skills/draft.md",
      "output_schema": "schemas/draft.schema.json"
    }
  ]
}

When input.schema is present, AI Core loads its packaged schema file into both the intake-classification prompt and every step prompt. When it is absent, no input-schema section is added. Missing required input can produce a checkpoint before step 0; the host asks for the missing details and resumes the pipeline.

model_slots are plugin-level model binding points, not separate actions. Actions and pipeline steps can point at a generation slot through model_slot, and the runtime can seed missing bindings from core.default. Routing always uses the single app-level routing model and is not a plugin slot.

Minimal Wasm Action Package

A Wasm package declares actions and an entrypoint module:

{
  "kind": "wasm",
  "plugin": {
    "id": "example_actions",
    "version": "0.1.0"
  },
  "requirements": {
    "core": "^0.1.0",
    "plugin_api": "^0.1.0"
  },
  "entrypoint": {
    "wasm": "wasm/example_actions.wasm"
  },
  "actions": [
    {
      "id": "summarize",
      "input_schema": "schemas/summarize.input.schema.json",
      "output_schema": "schemas/summarize.output.schema.json"
    }
  ]
}

Hosts call installed Wasm actions by plugin_id and fully qualified action_id, for example example_actions.summarize.

Build A Package

Normal marketplace package:

aip-pack developer-sign \
  --root /path/to/package \
  --developer-public-key /secure/developer.public.key \
  --developer-private-key /secure/developer.private.key \
  --output /out/example.aip

Developer package:

aip-pack-for-developers developer-sign \
  --root /path/to/package \
  --developer-public-key /secure/developer.public.key \
  --developer-private-key /secure/developer.private.key \
  --output /out/example.dev.aip

No-marketplace package:

aip-pack-no-marketplace developer-sign \
  --root /path/to/package \
  --output /out/example.no-marketplace.aip

No-marketplace can also be developer-signed:

aip-pack-no-marketplace developer-sign \
  --root /path/to/package \
  --developer-public-key /secure/developer.public.key \
  --developer-private-key /secure/developer.private.key \
  --output /out/example.no-marketplace.signed.aip

No-marketplace builds can also stay unsigned. If you omit developer keys and do not request recipient encryption, aip-pack-no-marketplace writes a plaintext .aip archive. You can also developer-sign it for your own local or internal use without sending it through Marketplace.

What The Tool Does

aip-pack reads aip.template.json, scans the package root recursively, fills file paths, sizes, and BLAKE3 hashes, signs the manifest when keys are provided, and writes the final .aip.

The tool includes package content such as pipeline.json, Wasm modules, skills/, and schemas/. It excludes local source/build metadata such as dist/, target/, top-level src/, top-level tests/, README.md, Cargo.toml, Cargo.lock, Makefile, .gitignore, and the template itself.

Do not rely on the tool to pick the right files for you. Put only package content in the package root tree; anything left there is a candidate unless the tool explicitly skips it.

Changing any packaged file after signing invalidates the manifest hash. Rebuild the .aip after every content change.

Runtime Compatibility

AI Core validates these before a package becomes active:

• package format and manifest hash;
• plugin id and version;
• requirements.core;
• plugin API version;
• Wasm entrypoint and ABI version for Wasm packages;
• package trust and license material for normal marketplace packages.

If install fails, the previous active plugin version remains active.

Author Checklist

1. Declare requirements.core and requirements.plugin_api explicitly.
2. Keep aip.template.json declarative.
3. Put reusable prompt and instruction text under skills/.
4. Put schemas, examples, or output contracts under schemas/.
5. Install the resulting package into a compatible AI Core runtime artifact.