Skip to content

Component spec

A component is a packaged, versioned piece of software, plus everything needed to deploy it: its container image, metadata, defaults, the format of its inputs and outputs, and its management commands. Once registered, a component is searchable in the Component registry and can be deployed as a block.

At a glance

Submit with: POST /api/addComponent on the Parser.
Before this: build and push your container image (see Instance SDK).
After this: create a block from it (see Block spec).

Structure

Put the component's fields under body.spec.values:

{
  "header": {
    "templateUri": "Parser/V1",
    "parameters": {}
  },
  "body": {
    "spec": {
      "values": {
        ...
      }
    }
  }
}

The Parser processes the spec (add_component_IR) and saves it to the component registry.

Fields

Identity

Field Type Required Description
componentId.name string Yes Component name.
componentId.version string Yes Version.
componentId.releaseTag string Yes Release tag, for example stable or beta.
componentType string Yes Category, for example model, service or utility.
componentURI string Yes Unique URI, normally generated as <componentType>.<name>:<version>-<releaseTag>, for example model.object-detector:2.0.0-stable. Blocks refer to the component by this URI.
componentMetadata object No Free-form details, such as use case, framework and hardware.
tags array No Tags, for search.

Container images

Field Type Required Description
containerRegistryInfo object No The component's container image.
containerRegistryInfo.containerImage string Yes, if containerRegistryInfo is given Full image path.
containerRegistryInfo.containerRegistryId string Yes, if containerRegistryInfo is given ID of the registry that stores the image.
containerRegistryInfo.containerImageMetadata object No Details such as author and description.
containerRegistryInfo.componentMode string Yes, if containerRegistryInfo is given "aios" for a normal block, or "third_party" for a block backed by a third-party system.
containerRegistryInfo.initContainer object For managed third-party systems The init container that installs the third-party system. Same structure as containerRegistryInfo.

Defaults and behavior

These values are copied into each block created from the component, unless the block overrides them.

Field Type Description
componentInitData object Start-up data or configuration, such as weight paths or external URLs. Becomes the block's blockInitData.
componentInitSettings object Runtime settings, such as flags, modes or tuning. Becomes the block's initSettings.
componentParameters object Processing or inference parameters that can change at runtime. Becomes the block's parameters.
policies object Default policies for blocks created from this component.
componentManagementCommandsTemplate object The management commands the component supports, and their arguments.

Protocols (input, output and configuration formats)

Field Describes
componentInputProtocol The inputs the component accepts.
componentOutputProtocol The outputs it produces.
componentInitSettingsProtocol The structure of componentInitSettings.
componentInitParametersProtocol The structure of componentParameters.

Writing protocols

A protocol is a JSON schema that describes data: its type, limits, description and, for objects and arrays, its nested structure. Protocols let people and tools understand what a component expects and produces.

Attribute Type Description
type string string, number, boolean, array, object or any.
description string What the field is for.
pattern string For strings: a regular expression the value must match.
length number Maximum string length.
min, max number Allowed numeric range.
choices array The allowed values.
max_length number Maximum number of array elements.
properties object For objects: the nested fields.
items object For arrays: the schema of each element.
{
  "image": {
    "type": "string",
    "description": "Base64 encoded image input",
    "pattern": "^data:image/.*;base64,"
  },
  "metadata": {
    "type": "object",
    "description": "Optional metadata associated with the input",
    "properties": {
      "source": { "type": "string" },
      "timestamp": { "type": "number" }
    }
  }
}
{
  "predictions": {
    "type": "array",
    "description": "Top prediction results",
    "max_length": 5,
    "items": {
      "type": "object",
      "properties": {
        "label": { "type": "string" },
        "confidence": { "type": "number", "min": 0.0, "max": 1.0 }
      }
    }
  },
  "runtime_ms": {
    "type": "number",
    "description": "Inference time in milliseconds"
  }
}
{
  "logging_level": {
    "type": "string",
    "description": "Logging verbosity level",
    "choices": ["debug", "info", "warn", "error"]
  },
  "enable_cache": {
    "type": "boolean",
    "description": "Whether to enable cache during execution"
  },
  "max_threads": {
    "type": "number",
    "description": "Maximum threads the component can spawn",
    "min": 1,
    "max": 64
  }
}
{
  "threshold": {
    "type": "number",
    "description": "Minimum confidence required to accept a prediction",
    "min": 0.0,
    "max": 1.0
  },
  "top_k": {
    "type": "number",
    "description": "Number of top predictions to return",
    "min": 1,
    "max": 10
  },
  "class_filter": {
    "type": "array",
    "description": "Limit predictions to specific class labels",
    "choices": ["cat", "dog", "car", "tree"],
    "max_length": 4
  }
}

Example: object detection component

{
  "header": {
    "templateUri": "Parser/V1",
    "parameters": {}
  },
  "body": {
    "spec": {
      "values": {
        "componentId": {
          "name": "object-detector",
          "version": "2.0.0",
          "releaseTag": "stable"
        },
        "componentURI": "model.object-detector:2.0.0-stable",
        "componentType": "model",

        "containerRegistryInfo": {
          "containerImage": "registry.ai-platform.com/models/object-detector:2.0.0",
          "containerRegistryId": "ai-platform-registry",
          "containerImageMetadata": {
            "author": "vision-team",
            "description": "YOLO-based real-time object detection model"
          },
          "componentMode": "aios"
        },

        "componentMetadata": {
          "usecase": "real-time object detection",
          "framework": "PyTorch",
          "hardware": "GPU"
        },

        "componentInitData": {
          "weights_path": "/models/yolov5s.pt",
          "device": "cuda"
        },

        "componentInputProtocol": {
          "image": {
            "type": "string",
            "description": "Input image encoded as Base64",
            "pattern": "^data:image/.*;base64,"
          },
          "image_shape": {
            "type": "array",
            "description": "Height and width of the input image",
            "max_length": 2,
            "items": {
              "type": "number",
              "min": 1
            }
          }
        },

        "componentOutputProtocol": {
          "detections": {
            "type": "array",
            "description": "Detected objects",
            "items": {
              "type": "object",
              "properties": {
                "class": { "type": "string" },
                "confidence": { "type": "number", "min": 0.0, "max": 1.0 },
                "bbox": {
                  "type": "array",
                  "description": "Bounding box [x_min, y_min, x_max, y_max]",
                  "max_length": 4,
                  "items": { "type": "number" }
                }
              }
            }
          },
          "processing_time_ms": {
            "type": "number",
            "description": "Inference time in milliseconds"
          }
        },

        "componentInitParametersProtocol": {
          "threshold": {
            "type": "number",
            "description": "Confidence threshold for filtering predictions",
            "min": 0.0,
            "max": 1.0
          },
          "top_k": {
            "type": "number",
            "description": "Return top-K detections per image",
            "min": 1,
            "max": 50
          }
        },

        "componentInitSettingsProtocol": {
          "enable_tracing": {
            "type": "boolean",
            "description": "Enable performance tracing logs"
          },
          "batch_size": {
            "type": "number",
            "description": "Batch size to be used during inference",
            "min": 1,
            "max": 32
          }
        },

        "policies": {
          "resource_affinity": {
            "nodeType": "gpu",
            "minMemory": "4GB"
          }
        },

        "componentManagementCommandsTemplate": {
          "restart": {
            "description": "Restart the model service",
            "args": {}
          },
          "reload_weights": {
            "description": "Reload model weights from disk",
            "args": {
              "weights_path": {
                "type": "string",
                "required": true
              }
            }
          }
        },

        "componentParameters": {
          "threshold": 0.4,
          "top_k": 10
        },

        "componentInitSettings": {
          "enable_tracing": true,
          "batch_size": 4
        },

        "tags": ["vision", "object-detection", "yolo", "realtime"]
      }
    }
  }
}

Component spec example with init container

A chat component backed by a vLLM server that AIOS installs automatically. Note componentMode: "third_party" and the initContainer entry.

{
  "header": {
    "templateUri": "Parser/V1",
    "parameters": {}
  },
  "body": {
    "spec": {
      "values": {
        "componentId": {
          "name": "vllm-chat",
          "version": "1.0.0",
          "releaseTag": "stable"
        },
        "componentType": "model",
        "containerRegistryInfo": {
          "containerImage": "registry.ai-platform.com/models/vllm-external-chat:2.0.0",
          "containerRegistryId": "ai-platform-registry",
          "containerImageMetadata": {
            "author": "llm-team",
            "description": "LLM team"
          },
          "componentMode": "third_party",
          "initContainer": {
            "containerImage": "registry.ai-platform.com/init-containers/vLLM-deployer:2.0.0",
            "containerRegistryId": "ai-platform-registry",
            "containerImageMetadata": {
              "author": "vision-team",
              "description": "Init container to deploy vLLM system"
            }
          }
        },
        "componentMetadata": {
          "usecase": "chat-completion",
          "framework": "external-api",
          "hardware": "external"
        },
        "componentInitData": {
          "vllm_server_url": "http://vllm-service:8080",
          "model_name": "mistralai/Mistral-7B-Instruct-v0.1"
        },
        "componentInitParametersProtocol": {
          "temperature": {
            "type": "number",
            "description": "Sampling temperature",
            "min": 0.0,
            "max": 2.0
          }
        },
        "componentInitSettingsProtocol": {
          "max_new_tokens": {
            "type": "number",
            "description": "Maximum number of tokens to generate",
            "min": 1,
            "max": 2048
          }
        },
        "componentInputProtocol": {
          "message": {
            "type": "string",
            "description": "Input message from the user"
          },
          "session_id": {
            "type": "string",
            "description": "Unique identifier for the chat session"
          }
        },
        "componentOutputProtocol": {
          "reply": {
            "type": "string",
            "description": "Chat reply from the vLLM model"
          }
        },
        "componentParameters": {
          "temperature": 0.7
        },
        "componentInitSettings": {
          "max_new_tokens": 256
        },
        "componentManagementCommandsTemplate": {
          "reset": {
            "description": "Clears all stored chat sessions",
            "args": {}
          }
        },
        "tags": ["vllm", "chat", "openai-compatible", "mistral", "llm"]
      }
    }
  }
}

Register the component

curl -X POST http://<parser-url>/api/addComponent \
  -H "Content-Type: application/json" \
  -d @component_spec.json

Next: create a block from it.