Skip to content

Component registry

The component registry is the catalog of every component registered in the network: packaged, versioned software that can be deployed as a block. Developers publish components to it, and anyone can browse, search and deploy them.

At a glance

Runs on: the management cluster, as components-registry-svc (NodePort 30112).
Interfaces: REST and GraphQL (with a GraphiQL browser UI).
To register a component: use the Parser's addComponent action (Component spec), which validates it and calls this registry for you.

What it stores

For each component: identity and version, metadata, container images (instance, sidecars, init container), input/output protocols, management command templates, settings and parameter protocols, and default settings and parameters. The fields are explained in Component spec.

Full database schema (click to expand)
// Sub-schema for componentId
const componentIdSchema = new mongoose.Schema({
  name: { type: String, required: true }, // Component name
  version: { type: String, required: true }, // Component version
  releaseTag: { type: String, required: true }  // Component release tag
}, { _id: false })

// Sub-schema for containerRegistryInfo
const containerRegistryInfoSchema = new mongoose.Schema({
  containerImage: { type: String, required: true }, // Image path in registry
  containerRegistryId: { type: String, required: true }, // Registry identifier
  containerImageMetadata: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Arbitrary metadata (description, author, etc.)
  componentMode: { type: String, enum: ['aios', 'third_party'], required: true }, // Component origin

  // init container: specified only if the componentMode = "third_party"
  initContainer: { type: mongoose.SchemaTypes.Mixed, default: {} }

}, { _id: false })

const componentSchema = new mongoose.Schema({
  createdAt: { type: Date, default: Date.now }, // Creation timestamp (sys generated)
  lastModifiedAt: { type: Date, default: Date.now }, // Last modified timestamp (sys generated)

  componentId: { type: componentIdSchema, required: true }, // Structured component identity
  componentType: { type: String, required: true },

  // Unique URI (assigned internally - system generated) - {<componentType>.<componentId.name>:<componentId.version>-<componentId.releaseTag}
  componentURI: { type: String, required: true, index: true }, 

  containerRegistryInfo: { type: containerRegistryInfoSchema, required: false }, // Container registry information

  componentMetadata: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Custom metadata

  componentInitData: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Initial data/config needed to start
  componentInputProtocol: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Input protocol or data schema
  componentOutputProtocol: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Output protocol or data schema
  policies: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Attached policies

  componentManagementCommandsTemplate: { type: mongoose.SchemaTypes.Mixed, default: {} }, // List of management commands supported
  componentInitSettings: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Runtime settings or flags
  componentParameters: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Param list for inference or processing

  componentInitSettingsProtocol: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Protocol/template of init settings
  componentInitParametersProtocol: { type: mongoose.SchemaTypes.Mixed, default: {} }, // Protocol/template of init params

  tags: [{ type: String }] // Free-form list of tags for search/filtering
})
Example record
{
        "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"]
}

REST APIs

All endpoints use POST. Components are identified by their componentURI (passed as uri).

Endpoint What it does
/api/registerComponent Register a component. Used internally by the Parser. The componentURI is generated from componentType, componentId.name, componentId.version and componentId.releaseTag, so don't include it. Fails if the URI already exists.
/api/unregisterComponent Delete a component.
/api/updateComponent Update fields with a MongoDB-style update.
/api/addMetadata Add or replace the component's metadata (validated before saving).
/api/updateMetadata Update metadata with MongoDB update operators.
/api/getByType Find components whose componentType matches a pattern (regex).
/api/getByURI Find components whose componentURI matches a pattern (regex).
/api/query Search with any MongoDB filter.
# Register (normally done by the Parser)
curl -X POST http://<server-url>/api/registerComponent \
  -H "Content-Type: application/json" \
  -d @./component.json

# Delete
curl -X POST http://<server-url>/api/unregisterComponent \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "parser.tokenizer:1.0-latest"
  }'

# Update
curl -X POST http://<server-url>/api/updateComponent \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "parser.tokenizer:1.0-latest",
    "data": {
      "$set": {
        "componentMetadata.description": "Updated tokenizer component"
      }
    }
  }'

# Add or replace metadata
curl -X POST http://<server-url>/api/addMetadata \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "parser.tokenizer:1.0-latest",
    "data": {
      "author": "AI Team",
      "build": "v1.2"
    }
  }'

# Update metadata
curl -X POST http://<server-url>/api/updateMetadata \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "parser.tokenizer:1.0-latest",
    "data": {
      "$set": {
        "metadata.author": "AIOS Team"
      }
    }
  }'

# Find by type
curl -X POST http://<server-url>/api/getByType \
  -H "Content-Type: application/json" \
  -d '{
    "typeString": "parser"
  }'

# Find by URI
curl -X POST http://<server-url>/api/getByURI \
  -H "Content-Type: application/json" \
  -d '{
    "uriString": "parser.tokenizer:1.0-latest"
  }'

# Search
curl -X POST http://<server-url>/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "tags": { "$in": ["production"] },
      "componentId.version": "1.0"
    }
  }'

GraphQL API

/gql: POST for queries, GET to open the GraphiQL playground in a browser (http://<server-url>/gql).

The GraphQL schema is read-only (no mutations). It is generated from the component model with graphql-compose-mongoose.

query {
  componentMany(filter: { componentType: "object-det" }) {
    componentURI
    componentId {
      name
      version
      releaseTag
    }
    componentMetadata
  }
}
query {
  componentById(_id: "661d44aa99a3a21f25ac9c70") {
    componentURI
    componentType
    componentId {
      name
      version
      releaseTag
    }
  }
}
curl -X POST http://<server-url>/gql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { componentMany(filter: { componentType: \"parser\" }) { componentURI componentType } }"
  }'