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. |
{
"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.