Init Catalog

Init Catalog Plugin

Scaffold a new catalog plugin end-to-end so it compiles and starts without panics.

Phase 1: Gather Inputs

Ask the user for all three in a single prompt:

• Plugin name — snake_case (e.g., agent, dataset, pipeline)
• Description — human-readable (e.g., "Agent catalog")
• Entities — comma-separated Name:type pairs where type is context, artifact, or execution (e.g., CatalogAgent:context,CatalogAgentArtifact:artifact)

Validate before proceeding:

• Name contains only lowercase letters, digits, and underscores
• At least one entity is provided
• Each entity has exactly one colon separating PascalCase name from type
• Each type is one of: context, artifact, execution

Phase 2: Run catalog-gen

make -C catalog gen/catalog-plugin NAME=<name> DESCRIPTION="<desc>" ENTITIES=<entity1>,<entity2>

Check exit code. Report files created.

Phase 3: Register Asset Type

New plugins must register their asset type in the shared catalog infrastructure so that sources can be scoped to the correct plugin via the model catalog's /sources endpoint.

The asset type value is derived from the primary entity's snake_case name, pluralized (e.g., entity CatalogAgent → catalog_agents, entity Agent → agents).

3a: Add to the OpenAPI enum

Edit api/openapi/src/catalog.yaml — find the CatalogAssetType enum and add the new value:

CatalogAssetType:
  type: string
  enum:
    - models
    - mcp_servers
    - <asset_type_value>    # e.g., agents
  default: models

3b: Add the Go constant

Edit catalog/internal/catalog/basecatalog/source_types.go — add to the AssetType constants:

const (
    AssetTypeModels     = "models"
    AssetTypeMCPServers = "mcp_servers"
    AssetType<PascalAssetType> = "<asset_type_value>"  // e.g., AssetTypeAgents = "agents"
)

3c: Add to the validation map

Edit catalog/internal/catalog/basecatalog/validation.go — add to the validAssetTypes map in ValidateNamedQueries:

validAssetTypes := map[string]bool{
    AssetTypeModels:     true,
    AssetTypeMCPServers: true,
    AssetType<PascalAssetType>: true,
}

Also update the error message format string to include the new constant.

3d: Add AssetType field to PluginSource (if not already present)

Check catalog/internal/catalog/basecatalog/source_types.go — the PluginSource struct must have an AssetType field. If missing, add it:

type PluginSource struct {
    Name       string                      `json:"name" yaml:"name"`
    ID         string                      `json:"id" yaml:"id"`
    Type       string                      `json:"type" yaml:"type"`
    Enabled    *bool                       `json:"enabled,omitempty" yaml:"enabled,omitempty"`
    Properties map[string]any              `json:"properties" yaml:"properties"`
    Labels     []string                    `json:"labels" yaml:"labels"`
    AssetType  *apimodels.CatalogAssetType `json:"assetType,omitempty" yaml:"assetType,omitempty"`

    Origin string `json:"-" yaml:"-"`
}

This matches the pattern used by MCPSource.

Phase 4: Replace Panic TODOs

All 8 panics are in the generated entity service files at: catalog/internal/catalog/<name>catalog/service/<entity_snake>.go

Read each generated service file first to get the exact function signatures with concrete entity names. Then replace each panic using the recipes below.

Type Reference Table

Use this table to select the correct types, mappers, and table names for each entity's datastore type:

The service alias refers to github.com/kubeflow/hub/internal/platform/db/repository (already imported in the generated file).

Reference implementations

Before writing code, read these files for the exact patterns:

• Context entities: catalog/internal/catalog/mcpcatalog/service/mcp_server.go
• Artifact entities: catalog/internal/catalog/modelcatalog/service/catalog_model_artifact.go
• Execution entities: catalog/internal/catalog/mcpcatalog/service/mcp_server_tool.go

Panic recipes

Each group of panics is documented in a separate file. Read the file for each group before implementing.

• Panics 1–3 (entity ↔ schema mapping): Read .agents/skills/init-catalog/panic-mapping.md
• Panics 4–5 (filtering & ordering): Read .agents/skills/init-catalog/panic-ordering.md
• Panics 6–8 (delete/query ops, imports, Save override): Read .agents/skills/init-catalog/panic-crud.md

Phase 5: Generate OpenAPI Stubs

Three make targets must run in order:

# 1. Rebuild the merged catalog spec to include the new plugin
make api/openapi/catalog.yaml

# 2. Generate server stubs (controller, routes, type_asserts)
make -C catalog gen/openapi-server

# 3. Generate client model types (type_asserts.go references these)
make -C catalog gen/openapi

Step 3 is critical — gen/openapi-server produces type_asserts.go which references client model types (e.g., model.Agent, model.AgentList) from catalog/pkg/openapi/. Without gen/openapi, those types don't exist and the build fails.

Verify that these files were created or updated:

• catalog/internal/server/openapi/api_<name>_catalog_service.go
• catalog/internal/server/openapi/api_<name>.go
• catalog/pkg/openapi/model_<entity_snake>.go (one per entity)

Phase 6: Implement DB Provider

The generated db_<name>.go has a TODO stub. Replace it with a working implementation that queries the repository and maps results to OpenAPI models.

1. Export the type: rename the struct from db<PascalName>CatalogImpl to DB<PascalName>Catalog so the service implementation can reference it.

2. Add a List<PascalName>sParams struct with fields: Name, SourceIDs, FilterQuery, OrderBy, SortOrder, NextPageToken, PageSize.

3. Add List<Entity>s method: build ListOptions from params, call repository .List(), map each result via a mapping function, return the API list type with pagination. For pointer fields on the list struct (check catalog/pkg/openapi/model_<entity>_list.go), use &variable or new(value) (Go 1.26 builtin). The NextPageToken from the repository is a plain string; only assign to the response if non-empty (the API model field is *string).

4. Add Get<Entity> method: parse ID string to int32, call repository .GetByID(), map via the mapping function, return or 404.

5. Implement mapDB<Entity>ToAPI mapping function: map ID (format int64 → string), Name from attributes, then loop over Properties matching by name:

   • String fields: res.<Field> = prop.StringValue
   • Boolean fields: res.<Field> = prop.BoolValue
   • Array fields: json.Unmarshal from prop.StringValue into []string

   Reference: catalog/internal/catalog/modelcatalog/db_catalog.go function mapDBModelToAPIModel.

6. Remove the var _ sharedmodels.CatalogSourceRepository placeholder and the TODO comments.