agent-starter-pack 0.8.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

src/cli/main.py

@@ -18,6 +18,7 @@ import click
 from rich.console import Console
 
 from .commands.create import create
+from .commands.list import list_agents
 from .commands.setup_cicd import setup_cicd
 from .utils import display_update_message
 
@@ -53,6 +54,7 @@ def cli() -> None:
 # Register commands
 cli.add_command(create)
 cli.add_command(setup_cicd)
+cli.add_command(list_agents, name="list")
 
 
 if __name__ == "__main__":

src/cli/utils/remote_template.py

@@ -0,0 +1,254 @@
+# Copyright 2025 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
+#
+#     http://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.
+
+import logging
+import os
+import pathlib
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class RemoteTemplateSpec:
+    """Parsed remote template specification."""
+
+    repo_url: str
+    template_path: str
+    git_ref: str
+    is_adk_samples: bool = False
+
+
+def parse_agent_spec(agent_spec: str) -> RemoteTemplateSpec | None:
+    """Parse agent specification to determine if it's a remote template.
+
+    Args:
+        agent_spec: Agent specification string
+
+    Returns:
+        RemoteTemplateSpec if remote template, None if local template
+    """
+    # Check for local@ prefix
+    if agent_spec.startswith("local@"):
+        return None
+
+    # Check for adk@ shortcut
+    if agent_spec.startswith("adk@"):
+        sample_name = agent_spec[4:]  # Remove "adk@" prefix
+        return RemoteTemplateSpec(
+            repo_url="https://github.com/google/adk-samples",
+            template_path=f"python/agents/{sample_name}",
+            git_ref="main",
+            is_adk_samples=True,
+        )
+
+    # GitHub /tree/ URL pattern
+    tree_pattern = r"^(https?://[^/]+/[^/]+/[^/]+)/tree/([^/]+)/(.*)$"
+    match = re.match(tree_pattern, agent_spec)
+    if match:
+        repo_url = match.group(1)
+        git_ref = match.group(2)
+        template_path = match.group(3)
+        return RemoteTemplateSpec(
+            repo_url=repo_url,
+            template_path=template_path.strip("/"),
+            git_ref=git_ref,
+        )
+
+    # General remote pattern: <repo_url>[/<path>][@<ref>]
+    # Handles github.com, gitlab.com, etc.
+    remote_pattern = r"^(https?://[^/]+/[^/]+/[^/]+)(?:/(.*?))?(?:@([^/]+))?/?$"
+    match = re.match(remote_pattern, agent_spec)
+    if match:
+        repo_url = match.group(1)
+        template_path_with_ref = match.group(2) or ""
+        git_ref_from_url = match.group(3)
+
+        # Separate path and ref if ref is part of the path
+        template_path = template_path_with_ref
+        git_ref = git_ref_from_url or "main"
+
+        if "@" in template_path:
+            path_parts = template_path.split("@")
+            template_path = path_parts[0]
+            git_ref = path_parts[1]
+
+        return RemoteTemplateSpec(
+            repo_url=repo_url,
+            template_path=template_path.strip("/"),
+            git_ref=git_ref,
+        )
+
+    # GitHub shorthand: <org>/<repo>[/<path>][@<ref>]
+    github_shorthand_pattern = r"^([^/]+)/([^/]+)(?:/(.*?))?(?:@([^/]+))?/?$"
+    match = re.match(github_shorthand_pattern, agent_spec)
+    if match and "/" in agent_spec:  # Ensure it has at least one slash
+        org = match.group(1)
+        repo = match.group(2)
+        template_path = match.group(3) or ""
+        git_ref = match.group(4) or "main"
+        return RemoteTemplateSpec(
+            repo_url=f"https://github.com/{org}/{repo}",
+            template_path=template_path,
+            git_ref=git_ref,
+        )
+
+    return None
+
+
+def fetch_remote_template(spec: RemoteTemplateSpec) -> pathlib.Path:
+    """Fetch remote template and return path to template directory.
+
+    Uses Git to clone the remote repository.
+
+    Args:
+        spec: Remote template specification
+
+    Returns:
+        Path to the fetched template directory
+    """
+    temp_dir = tempfile.mkdtemp(prefix="asp_remote_template_")
+    temp_path = pathlib.Path(temp_dir)
+    repo_path = temp_path / "repo"
+
+    # Attempt Git Clone
+    try:
+        clone_url = spec.repo_url
+        clone_cmd = [
+            "git",
+            "clone",
+            "--depth",
+            "1",
+            "--branch",
+            spec.git_ref,
+            clone_url,
+            str(repo_path),
+        ]
+        logging.debug(
+            f"Attempting to clone remote template with Git: {' '.join(clone_cmd)}"
+        )
+        # GIT_TERMINAL_PROMPT=0 prevents git from prompting for credentials
+        subprocess.run(
+            clone_cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            encoding="utf-8",
+            env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+        )
+        logging.debug("Git clone successful.")
+    except subprocess.CalledProcessError as e:
+        shutil.rmtree(temp_path, ignore_errors=True)
+        raise RuntimeError(f"Git clone failed: {e.stderr.strip()}") from e
+
+    # Process the successfully fetched template
+    try:
+        if spec.template_path:
+            template_dir = repo_path / spec.template_path
+        else:
+            template_dir = repo_path
+
+        if not template_dir.exists():
+            raise FileNotFoundError(
+                f"Template path not found in the repository: {spec.template_path}"
+            )
+
+        # Exclude Makefile and README.md from remote template to avoid conflicts
+        makefile_path = template_dir / "Makefile"
+        if makefile_path.exists():
+            logging.debug(f"Removing Makefile from remote template: {makefile_path}")
+            makefile_path.unlink()
+
+        readme_path = template_dir / "README.md"
+        if readme_path.exists():
+            logging.debug(f"Removing README.md from remote template: {readme_path}")
+            readme_path.unlink()
+
+        return template_dir
+    except Exception as e:
+        # Clean up on error
+        shutil.rmtree(temp_path, ignore_errors=True)
+        raise RuntimeError(
+            f"An unexpected error occurred after fetching remote template: {e}"
+        ) from e
+
+
+def load_remote_template_config(template_dir: pathlib.Path) -> dict[str, Any]:
+    """Load template configuration from remote template.
+
+    Args:
+        template_dir: Path to template directory
+
+    Returns:
+        Template configuration dictionary
+    """
+    config_path = template_dir / ".template" / "templateconfig.yaml"
+
+    if not config_path.exists():
+        return {}
+
+    try:
+        with open(config_path) as f:
+            config = yaml.safe_load(f)
+            return config if config else {}
+    except Exception as e:
+        logging.error(f"Error loading remote template config: {e}")
+        return {}
+
+
+def get_base_template_name(config: dict[str, Any]) -> str:
+    """Get base template name from remote template config.
+
+    Args:
+        config: Template configuration dictionary
+
+    Returns:
+        Base template name (defaults to "adk_base")
+    """
+    return config.get("base_template", "adk_base")
+
+
+def merge_template_configs(
+    base_config: dict[str, Any], remote_config: dict[str, Any]
+) -> dict[str, Any]:
+    """Merge base template config with remote template config using a deep merge.
+
+    Args:
+        base_config: Base template configuration
+        remote_config: Remote template configuration
+
+    Returns:
+        Merged configuration with remote overriding base
+    """
+    import copy
+
+    def deep_merge(d1: dict[str, Any], d2: dict[str, Any]) -> dict[str, Any]:
+        """Recursively merges d2 into d1."""
+        for k, v in d2.items():
+            if k in d1 and isinstance(d1[k], dict) and isinstance(v, dict):
+                d1[k] = deep_merge(d1[k], v)
+            else:
+                d1[k] = v
+        return d1
+
+    # Start with a deep copy of the base to avoid modifying it
+    merged_config = copy.deepcopy(base_config)
+
+    # Perform the deep merge
+    return deep_merge(merged_config, remote_config)

src/cli/utils/template.py

@@ -29,6 +29,9 @@ from rich.prompt import IntPrompt, Prompt
 from src.cli.utils.version import get_current_version
 
 from .datastores import DATASTORES
+from .remote_template import (
+    get_base_template_name,
+)
 
 ADK_FILES = ["app/__init__.py"]
 NON_ADK_FILES: list[str] = []
@@ -69,7 +72,7 @@ class TemplateConfig:
 
 
 OVERWRITE_FOLDERS = ["app", "frontend", "tests", "notebooks"]
-TEMPLATE_CONFIG_FILE = ".templateconfig.yaml"
+TEMPLATE_CONFIG_FILE = "templateconfig.yaml"
 DEPLOYMENT_FOLDERS = ["cloud_run", "agent_engine"]
 DEFAULT_FRONTEND = "streamlit"
 
@@ -94,7 +97,7 @@ def get_available_agents(deployment_target: str | None = None) -> dict:
 
     for agent_dir in agents_dir.iterdir():
         if agent_dir.is_dir() and not agent_dir.name.startswith("__"):
-            template_config_path = agent_dir / "template" / ".templateconfig.yaml"
+            template_config_path = agent_dir / ".template" / "templateconfig.yaml"
             if template_config_path.exists():
                 try:
                     with open(template_config_path) as f:
@@ -154,15 +157,20 @@ def load_template_config(template_dir: pathlib.Path) -> dict[str, Any]:
         return {}
 
 
-def get_deployment_targets(agent_name: str) -> list:
+def get_deployment_targets(
+    agent_name: str, remote_config: dict[str, Any] | None = None
+) -> list:
     """Get available deployment targets for the selected agent."""
-    template_path = (
-        pathlib.Path(__file__).parent.parent.parent.parent
-        / "agents"
-        / agent_name
-        / "template"
-    )
-    config = load_template_config(template_path)
+    if remote_config:
+        config = remote_config
+    else:
+        template_path = (
+            pathlib.Path(__file__).parent.parent.parent.parent
+            / "agents"
+            / agent_name
+            / ".template"
+        )
+        config = load_template_config(template_path)
 
     if not config:
         return []
@@ -171,9 +179,11 @@ def get_deployment_targets(agent_name: str) -> list:
     return targets if isinstance(targets, list) else [targets]
 
 
-def prompt_deployment_target(agent_name: str) -> str:
+def prompt_deployment_target(
+    agent_name: str, remote_config: dict[str, Any] | None = None
+) -> str:
     """Ask user to select a deployment target for the agent."""
-    targets = get_deployment_targets(agent_name)
+    targets = get_deployment_targets(agent_name, remote_config=remote_config)
 
     # Define deployment target friendly names and descriptions
     TARGET_INFO = {
@@ -272,7 +282,7 @@ def prompt_datastore_selection(
         pathlib.Path(__file__).parent.parent.parent.parent
         / "agents"
         / agent_name
-        / "template"
+        / ".template"
     )
     config = load_template_config(template_path)
 
@@ -349,7 +359,7 @@ def prompt_datastore_selection(
 def get_template_path(agent_name: str, debug: bool = False) -> pathlib.Path:
     """Get the absolute path to the agent template directory."""
     current_dir = pathlib.Path(__file__).parent.parent.parent.parent
-    template_path = current_dir / "agents" / agent_name / "template"
+    template_path = current_dir / "agents" / agent_name / ".template"
     if debug:
         logging.debug(f"Looking for template in: {template_path}")
         logging.debug(f"Template exists: {template_path.exists()}")
@@ -397,6 +407,8 @@ def process_template(
     datastore: str | None = None,
     session_type: str | None = None,
     output_dir: pathlib.Path | None = None,
+    remote_template_path: pathlib.Path | None = None,
+    remote_config: dict[str, Any] | None = None,
 ) -> None:
     """Process the template directory and create a new project.
 
@@ -409,14 +421,30 @@ def process_template(
         datastore: Optional datastore type for data ingestion
         session_type: Optional session type for cloud_run deployment
         output_dir: Optional output directory path, defaults to current directory
+        remote_template_path: Optional path to remote template for overlay
+        remote_config: Optional remote template configuration
     """
     logging.debug(f"Processing template from {template_dir}")
     logging.debug(f"Project name: {project_name}")
     logging.debug(f"Include pipeline: {datastore}")
     logging.debug(f"Output directory: {output_dir}")
 
-    # Get paths
-    agent_path = template_dir.parent  # Get parent of template dir
+    # Handle remote vs local templates
+    is_remote = remote_template_path is not None
+
+    if is_remote:
+        # For remote templates, determine the base template
+        base_template_name = get_base_template_name(remote_config or {})
+        agent_path = (
+            pathlib.Path(__file__).parent.parent.parent.parent
+            / "agents"
+            / base_template_name
+        )
+        logging.debug(f"Remote template using base: {base_template_name}")
+    else:
+        # For local templates, use the existing logic
+        agent_path = template_dir.parent  # Get parent of template dir
+
     logging.debug(f"agent path: {agent_path}")
     logging.debug(f"agent path exists: {agent_path.exists()}")
     logging.debug(
@@ -489,7 +517,7 @@ def process_template(
             copy_frontend_files(frontend_type, project_template)
             logging.debug(f"4. Processed frontend files for type: {frontend_type}")
 
-            # 5. Finally, copy agent-specific files to override everything else
+            # 5. Copy agent-specific files to override base template
             if agent_path.exists():
                 for folder in OVERWRITE_FOLDERS:
                     agent_folder = agent_path / folder
@@ -500,11 +528,27 @@ def process_template(
                             agent_folder, project_folder, agent_name, overwrite=True
                         )
 
+            # 6. Finally, overlay remote template files if present
+            if is_remote and remote_template_path:
+                logging.debug(
+                    f"6. Overlaying remote template files from {remote_template_path}"
+                )
+                copy_files(
+                    remote_template_path,
+                    project_template,
+                    agent_name=agent_name,
+                    overwrite=True,
+                )
+
             # Load and validate template config first
-            template_path = pathlib.Path(template_dir)
-            config = load_template_config(template_path)
+            if is_remote:
+                config = remote_config or {}
+            else:
+                template_path = pathlib.Path(template_dir)
+                config = load_template_config(template_path)
+
             if not config:
-                raise ValueError(f"Could not load template config from {template_path}")
+                raise ValueError("Could not load template config")
 
             # Validate deployment target
             available_targets = config.get("settings", {}).get("deployment_targets", [])
@@ -516,8 +560,8 @@ def process_template(
                     f"Invalid deployment target '{deployment_target}'. Available targets: {available_targets}"
                 )
 
-            # Load template config
-            template_config = load_template_config(pathlib.Path(template_dir))
+            # Use the already loaded config
+            template_config = config
 
             # Check if data processing should be included
             if include_data_ingestion and datastore:
@@ -625,9 +669,36 @@ def process_template(
                         file_path.unlink()
                         logging.debug(f"Deleted {file_path}")
 
-                # After copying template files, handle the lock file
-                if deployment_target:
-                    # Get the source lock file path
+                # Handle pyproject.toml and uv.lock files
+                if is_remote and remote_template_path:
+                    # For remote templates, use their pyproject.toml and uv.lock if they exist
+                    remote_pyproject = remote_template_path / "pyproject.toml"
+                    remote_uv_lock = remote_template_path / "uv.lock"
+
+                    if remote_pyproject.exists():
+                        shutil.copy2(
+                            remote_pyproject, final_destination / "pyproject.toml"
+                        )
+                        logging.debug("Used pyproject.toml from remote template")
+
+                    if remote_uv_lock.exists():
+                        shutil.copy2(remote_uv_lock, final_destination / "uv.lock")
+                        logging.debug("Used uv.lock from remote template")
+                    elif deployment_target:
+                        # Fallback to base template lock file
+                        base_template_name = get_base_template_name(remote_config or {})
+                        lock_path = (
+                            pathlib.Path(__file__).parent.parent.parent.parent
+                            / "src"
+                            / "resources"
+                            / "locks"
+                            / f"uv-{base_template_name}-{deployment_target}.lock"
+                        )
+                        if lock_path.exists():
+                            shutil.copy2(lock_path, final_destination / "uv.lock")
+                            logging.debug(f"Used fallback lock file from {lock_path}")
+                elif deployment_target:
+                    # For local templates, use the existing logic
                     lock_path = (
                         pathlib.Path(__file__).parent.parent.parent.parent
                         / "src"
@@ -706,8 +777,12 @@ def copy_files(
             return True
         if "__pycache__" in str(path) or path.name == "__pycache__":
             return True
+        if ".git" in path.parts:
+            return True
         if agent_name is not None and should_exclude_path(path, agent_name):
             return True
+        if path.is_dir() and path.name == ".template":
+            return True
         return False
 
     if src.is_dir():