Skip to main content

Packaging & Interfaces for AI Products

An AI Product must declare how it is packaged and how consumers interact with it.
This ensures it is self-service, portable, and interoperable across environments.

Why Packaging & Interfaces Matter​

  • Self-Service → Consumers must integrate AI Products without bespoke engineering.
  • Portability → Packaging ensures consistent behavior across deployment targets.
  • Governance & Compliance → Interfaces define what consumers can (and cannot) do.
  • Interoperability → Enables composition with other products and services.

Packaging Formats​

AI Products may be packaged in one or more of the following forms:

  1. API / Service Endpoint

    • REST, gRPC, GraphQL, WebSocket, or specialized AI protocols.
    • Must provide machine-readable API documentation (e.g., OpenAPI, AsyncAPI).

  2. Container Image

    • Packaged as Docker/OCI containers for cloud or on-prem deployment.
    • Enables portability across environments.

  3. SDK / Library

    • Delivered as installable libraries (Python, JavaScript, Java, etc.).
    • Useful for embedding into applications or agent runtimes.

  4. Model Package

    • Distributed in model exchange formats (ONNX, TensorFlow SavedModel, PyTorch TorchScript).
    • May include associated preprocessing/postprocessing code.

Note:
All AI Products, regardless of packaging format, must be registered in a trustworthy discovery mechanism such as a catalog or marketplace.
Packaging defines how the product runs. Discovery defines how the product is found.

Interfaces​

Every AI Product must declare its interfaces for consumption:

  • Input / Output Schemas

    • Define expected inputs and outputs (structured, unstructured, multimodal).
    • Must be machine-readable (e.g., JSON Schema, Avro, Protobuf).

  • Invocation Modes

    • Batch, streaming, or interactive.
    • May support both synchronous and asynchronous execution.

  • Error Handling & Contracts

    • Must define error codes, fallback behaviors, and limits (timeouts, quotas).

  • Security Interfaces

    • Authentication/authorization mechanisms (OAuth2, API keys, service accounts).
    • Access policies declared in Security & Access Controls.

Metadata Requirements​

Packaging and interfaces must include:

  • Versioning information → aligned with Versioning & Lifecycle.
  • Dependencies → runtime, libraries, models, or external services.
  • Compliance declarations → license, usage restrictions, prohibited uses.

Example​

Text Classification AI Product

  • Packaging: Docker container + REST API + PyPI SDK.
  • Interfaces:
    • Input: JSON schema with text field.
    • Output: JSON schema with label and confidence_score.
  • Security: OAuth2 authentication.
  • Compliance: Licensed under Apache 2.0, prohibited for surveillance use.

Summary​

  • Packaging defines how an AI Product is delivered (API, container, SDK, model package, marketplace artifact).
  • Interfaces define how it is consumed (schemas, invocation modes, error handling, security).
  • Together, they ensure AI Products are self-service, portable, and trustworthy.

Principle: If packaging and interfaces are not clearly defined, the AI Product remains an asset — not a product.