Remove notion of "custom catalogs" from agent SDK (#705)

* Remove notion of "custom catalogs" from agent SDK

The basic catalog maintained by the A2UI team has no difference from
third-party catalogs.

This PR removes the notion of custom catalogs. Each catalog provided at
runtime should be independent and immutable. At build time, catalogs can
refer to components from other catalogs. They need to be bundled into a
free-standing one using the `tools/build_catalog/build_catalog.py`
script.

Fixes #650

* Refactor: extract basic catalog logic into its own package

Author: nan-yu

a2a_agents/python/a2ui_agent/agent_development.md

@@ -6,7 +6,7 @@ This guide explains how to build AI agents that generate A2UI interfaces using t
 
 The `a2ui_agent` SDK revolves around three main classes:
 
-*   **`CustomCatalogConfig`**: Defines the metadata for a component catalog (name, schema path, examples path).
+*   **`CatalogConfig`**: Defines the metadata for a component catalog (name, schema path, examples path).
 *   **`A2uiCatalog`**: Represents a processed catalog, providing methods for validation and LLM instruction rendering.
 *   **`A2uiSchemaManager`**: The central coordinator that loads catalogs, manages versioning, and generates system prompts.
 
@@ -17,24 +17,29 @@ The `a2ui_agent` SDK revolves around three main classes:
 The first step in any A2UI-enabled agent is initializing the `A2uiSchemaManager`.
 
 ```python
-from a2ui.inference.schema.manager import A2uiSchemaManager, CustomCatalogConfig
+from a2ui.inference.schema.constants import VERSION_0_8
+from a2ui.inference.schema.manager import A2uiSchemaManager, CatalogConfig
+from a2ui.inference.basic_catalog.provider import BasicCatalog
 
 schema_manager = A2uiSchemaManager(
-    version="0.8",
-    basic_examples_path="path/to/basic/examples",
-    custom_catalogs=[
-        CustomCatalogConfig(
+    version=VERSION_0_8,
+    catalogs=[
+        BasicCatalog.get_config(
+            version=VERSION_0_8,
+            examples_path="examples"
+        ),
+        CatalogConfig.from_path(
             name="my_custom_catalog",
             catalog_path="path/to/catalog.json",
             examples_path="path/to/examples"
-        )
-    ]
+        ),
+    ],
 )
 ```
 
 Notes:
-- The `custom_catalogs` parameter is optional. If not provided, the schema manager will use the basic catalog maintained by the A2UI team.
-- The provided custom catalog must be freestanding, i.e. it should not reference any external schemas or components, except for the common types.
+- The `catalogs` parameter is optional. If not provided, the schema manager will use the basic catalog maintained by the A2UI team.
+- The provided catalogs must be freestanding, i.e. they should not reference any external schemas or components, except for the common types.
 - If you have a modular catalog that references other catalogs, refer to [Freestanding Catalogs](../../../docs/catalogs.md#freestanding-catalogs) for more information.
 
 ### Step 2: Generate System Prompt

a2a_agents/python/a2ui_agent/pack_specs_hook.py

@@ -14,41 +14,58 @@
 
 import importlib.util
 import os
+import sys
 import shutil
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 
 
-def load_constants(project_root):
-  """Loads the shared constants module directly from its path in src/."""
-  constants_path = os.path.join(
-      project_root, "src", "a2ui", "inference", "schema", "constants.py"
-  )
-  if not os.path.exists(constants_path):
-    raise RuntimeError(f"Could not find shared constants at {constants_path}")
+def load_module(project_root, rel_path, filename, module_name):
+  """Loads a module directly from its path in src/."""
+  path = os.path.join(project_root, "src", rel_path.replace(".", os.sep), filename)
+  if not os.path.exists(path):
+    raise RuntimeError(f"Could not find module at {path}")
 
-  spec = importlib.util.spec_from_file_location("_constants_load", constants_path)
+  # Add src to sys.path so absolute imports work
+  src_path = os.path.abspath(os.path.join(project_root, "src"))
+  if src_path not in sys.path:
+    sys.path.insert(0, src_path)
+
+  spec = importlib.util.spec_from_file_location(module_name, path)
   if spec and spec.loader:
     module = importlib.util.module_from_spec(spec)
+    # Set the package context to allow relative imports if any
+    module.__package__ = rel_path
+    sys.modules[module_name] = module
     spec.loader.exec_module(module)
     return module
-  raise RuntimeError(f"Could not load shared constants from {constants_path}")
+  raise RuntimeError(f"Could not load module from {path}")
 
 
 class PackSpecsBuildHook(BuildHookInterface):
 
   def initialize(self, version, build_data):
     project_root = self.root
 
-    # Load constants dynamically from src/a2ui/inference/schema/constants.py
-    a2ui_constants = load_constants(project_root)
+    # Load constants and utils dynamically from src/
+    schema_path = "a2ui.inference.schema"
+    a2ui_constants = load_module(
+        project_root, schema_path, "constants.py", "_constants_load"
+    )
+    a2ui_utils = load_module(project_root, schema_path, "utils.py", "_utils_load")
+
+    basic_catalog_constants = load_module(
+        project_root,
+        "a2ui.inference.basic_catalog",
+        "constants.py",
+        "_basic_catalog_constants_load",
+    )
 
     spec_version_map = a2ui_constants.SPEC_VERSION_MAP
     a2ui_asset_package = a2ui_constants.A2UI_ASSET_PACKAGE
     specification_dir = a2ui_constants.SPECIFICATION_DIR
 
-    # project root is in a2a_agents/python/a2ui_agent
     # Dynamically find repo root by looking for specification_dir
-    repo_root = a2ui_constants.find_repo_root(project_root)
+    repo_root = a2ui_utils.find_repo_root(project_root)
     if not repo_root:
       # Check for PKG-INFO which implies a packaged state (sdist).
       # If PKG-INFO is present, trust the bundled assets.
@@ -66,23 +83,40 @@ def initialize(self, version, build_data):
         project_root, "src", a2ui_asset_package.replace(".", os.sep)
     )
 
-    for ver, schema_map in spec_version_map.items():
+    self._pack_schemas(repo_root, spec_version_map, target_base)
+    self._pack_basic_catalogs(
+        repo_root, basic_catalog_constants.BASIC_CATALOG_PATHS, target_base
+    )
+
+  def _pack_schemas(self, repo_root, spec_map, target_base):
+    for ver, schema_map in spec_map.items():
       target_dir = os.path.join(target_base, ver)
       os.makedirs(target_dir, exist_ok=True)
 
       for _schema_key, source_rel_path in schema_map.items():
-        source_path = os.path.join(repo_root, source_rel_path)
+        self._copy_schema(repo_root, source_rel_path, target_dir)
 
-        if not os.path.exists(source_path):
-          print(
-              f"WARNING: Source schema file not found at {source_path}. Build"
-              " might produce incomplete wheel if not running from monorepo"
-              " root."
-          )
-          continue
+  def _pack_basic_catalogs(self, repo_root, catalog_paths, target_base):
+    for ver, path_map in catalog_paths.items():
+      target_dir = os.path.join(target_base, ver)
+      os.makedirs(target_dir, exist_ok=True)
+
+      for _key, source_rel_path in path_map.items():
+        self._copy_schema(repo_root, source_rel_path, target_dir)
+
+  def _copy_schema(self, repo_root, source_rel_path, target_dir):
+    source_path = os.path.join(repo_root, source_rel_path)
+
+    if not os.path.exists(source_path):
+      print(
+          f"WARNING: Source schema file not found at {source_path}. Build"
+          " might produce incomplete wheel if not running from monorepo"
+          " root."
+      )
+      return
 
-        filename = os.path.basename(source_path)
-        dst_file = os.path.join(target_dir, filename)
+    filename = os.path.basename(source_path)
+    dst_file = os.path.join(target_dir, filename)
 
-        print(f"Copying {source_path} -> {dst_file}")
-        shutil.copy2(source_path, dst_file)
+    print(f"Copying {source_path} -> {dst_file}")
+    shutil.copy2(source_path, dst_file)

a2a_agents/python/a2ui_agent/src/a2ui/extension/a2ui_extension.py

@@ -94,7 +94,7 @@ def get_a2ui_agent_extension(
   """Creates the A2UI AgentExtension configuration.
 
   Args:
-      accepts_inline_catalogs: Whether the agent accepts inline custom catalogs.
+      accepts_inline_catalogs: Whether the agent accepts inline catalogs.
       supported_catalog_ids: All pre-defined catalogs the agent is known to support.
 
   Returns:

a2a_agents/python/a2ui_agent/src/a2ui/inference/basic_catalog/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .provider import BasicCatalog

a2a_agents/python/a2ui_agent/src/a2ui/inference/basic_catalog/constants.py

@@ -0,0 +1,25 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from ..schema.constants import CATALOG_SCHEMA_KEY, VERSION_0_8, VERSION_0_9
+
+BASIC_CATALOG_NAME = "basic"
+
+# Maps version to the relative path of the basic catalog schema in the source repo
+BASIC_CATALOG_PATHS = {
+    VERSION_0_8: {
+        CATALOG_SCHEMA_KEY: "specification/v0_8/json/standard_catalog_definition.json"
+    },
+    VERSION_0_9: {CATALOG_SCHEMA_KEY: "specification/v0_9/json/basic_catalog.json"},
+}

a2a_agents/python/a2ui_agent/src/a2ui/inference/basic_catalog/provider.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, Dict, Optional
+
+from ..schema.catalog import CatalogConfig
+from ..schema.catalog_provider import A2uiCatalogProvider
+from ..schema.utils import load_from_bundled_resource
+from ..schema.constants import BASE_SCHEMA_URL, CATALOG_ID_KEY, CATALOG_SCHEMA_KEY
+from .constants import BASIC_CATALOG_NAME, BASIC_CATALOG_PATHS
+
+
+class BundledCatalogProvider(A2uiCatalogProvider):
+  """Loads schemas from bundled package resources with fallbacks."""
+
+  def __init__(self, version: str):
+    self.version = version
+
+  def load(self) -> Dict[str, Any]:
+    # Use load_from_bundled_resource but with the specialized basic catalog paths
+    resource = load_from_bundled_resource(
+        self.version, CATALOG_SCHEMA_KEY, BASIC_CATALOG_PATHS
+    )
+
+    # Post-load processing for catalogs
+    if CATALOG_ID_KEY not in resource:
+      spec_map = BASIC_CATALOG_PATHS.get(self.version)
+      if spec_map and CATALOG_SCHEMA_KEY in spec_map:
+        rel_path = spec_map[CATALOG_SCHEMA_KEY]
+        # Strip the `json/` part from the catalog file path for the ID.
+        catalog_file = rel_path.replace("/json/", "/")
+        resource[CATALOG_ID_KEY] = BASE_SCHEMA_URL + catalog_file
+
+    if "$schema" not in resource:
+      resource["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+
+    return resource
+
+
+class BasicCatalog:
+  """Helper for accessing the basic A2UI catalog."""
+
+  @staticmethod
+  def get_config(version: str, examples_path: Optional[str] = None) -> CatalogConfig:
+    """Returns a CatalogConfig for the basic bundled catalog."""
+    return CatalogConfig(
+        name=BASIC_CATALOG_NAME,
+        provider=BundledCatalogProvider(version),
+        examples_path=examples_path,
+    )