agent-starter-pack 0.10.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

src/cli/commands/list.py

@@ -16,7 +16,7 @@ import logging
 import pathlib
 
 import click
-import yaml
+import tomllib
 from rich.console import Console
 from rich.table import Table
 
@@ -42,25 +42,37 @@ def display_agents_from_path(base_path: pathlib.Path, source_name: str) -> None:
         return
 
     found_agents = False
-    # Search for templateconfig.yaml files to identify agents
-    for config_path in sorted(base_path.glob("**/templateconfig.yaml")):
+    # Search for pyproject.toml files to identify agents (explicit opt-in)
+    for config_path in sorted(base_path.glob("**/pyproject.toml")):
         try:
-            with open(config_path, encoding="utf-8") as f:
-                config = yaml.safe_load(f)
+            with open(config_path, "rb") as f:
+                pyproject_data = tomllib.load(f)
 
-            agent_name = config.get("name", config_path.parent.parent.name)
-            description = config.get("description", "No description.")
+            config = pyproject_data.get("tool", {}).get("agent-starter-pack", {})
+
+            # Skip pyproject.toml files that don't have agent-starter-pack config
+            if not config:
+                continue
+
+            template_root = config_path.parent
+
+            # Use fallbacks to [project] section if needed
+            project_info = pyproject_data.get("project", {})
+            agent_name = (
+                config.get("name") or project_info.get("name") or template_root.name
+            )
+            description = (
+                config.get("description") or project_info.get("description") or ""
+            )
 
             # Display the agent's path relative to the scanned directory
-            relative_path = config_path.parent.parent.relative_to(base_path)
+            relative_path = template_root.relative_to(base_path)
 
             table.add_row(agent_name, f"/{relative_path}", description)
             found_agents = True
 
         except Exception as e:
-            logging.warning(
-                f"Could not load agent from {config_path.parent.parent}: {e}"
-            )
+            logging.warning(f"Could not load agent from {config_path.parent}: {e}")
 
     if not found_agents:
         console.print(f"No agents found in {source_name}", style="yellow")

src/cli/main.py

@@ -18,6 +18,7 @@ import click
 from rich.console import Console
 
 from .commands.create import create
+from .commands.enhance import enhance
 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(enhance)
 cli.add_command(setup_cicd)
 cli.add_command(list_agents, name="list")
 

src/cli/utils/logging.py

@@ -24,6 +24,46 @@ console = Console()
 F = TypeVar("F", bound=Callable[..., Any])
 
 
+def display_welcome_banner(
+    agent: str | None = None, enhance_mode: bool = False
+) -> None:
+    """Display the Agent Starter Pack welcome banner.
+
+    Args:
+        agent: Optional agent specification to customize the welcome message
+        enhance_mode: Whether this is for enhancement mode
+    """
+    if enhance_mode:
+        console.print(
+            "\n=== Google Cloud Agent Starter Pack 🚀===",
+            style="bold blue",
+        )
+        console.print(
+            "Enhancing your existing project with production-ready agent capabilities!\n",
+            style="green",
+        )
+    elif agent and agent.startswith("adk@"):
+        console.print(
+            "\n=== Welcome to [link=https://github.com/google/adk-samples]google/adk-samples[/link]! ✨ ===",
+            style="bold blue",
+        )
+        console.print(
+            "Powered by [link=https://goo.gle/agent-starter-pack]Google Cloud - Agent Starter Pack [/link]\n",
+        )
+        console.print(
+            "This tool will help you create an end-to-end production-ready AI agent in Google Cloud!\n"
+        )
+    else:
+        console.print(
+            "\n=== Google Cloud Agent Starter Pack 🚀===",
+            style="bold blue",
+        )
+        console.print("Welcome to the Agent Starter Pack!")
+        console.print(
+            "This tool will help you create an end-to-end production-ready AI agent in Google Cloud!\n"
+        )
+
+
 def handle_cli_error(f: F) -> F:
     """Decorator to handle CLI errors gracefully.
 

src/cli/utils/remote_template.py

@@ -22,7 +22,7 @@ import tempfile
 from dataclasses import dataclass
 from typing import Any
 
-import yaml
+import tomllib
 from jinja2 import Environment
 
 
@@ -183,27 +183,66 @@ def fetch_remote_template(
         ) from e
 
 
-def load_remote_template_config(template_dir: pathlib.Path) -> dict[str, Any]:
-    """Load template configuration from remote template.
+def load_remote_template_config(
+    template_dir: pathlib.Path, cli_overrides: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Load template configuration from remote template's pyproject.toml with CLI overrides.
+
+    Loads configuration from [tool.agent-starter-pack] section with fallbacks
+    to [project] section for name and description if not specified. CLI overrides
+    take precedence over all other sources.
 
     Args:
         template_dir: Path to template directory
+        cli_overrides: Configuration overrides from CLI (takes highest precedence)
 
     Returns:
-        Template configuration dictionary
+        Template configuration dictionary with merged sources
     """
-    config_path = template_dir / ".template" / "templateconfig.yaml"
-
-    if not config_path.exists():
-        return {}
-
-    try:
-        with open(config_path, encoding="utf-8") 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 {}
+    config = {}
+
+    # Start with defaults
+    defaults = {
+        "base_template": "adk_base",
+        "name": template_dir.name,
+        "description": "",
+    }
+    config.update(defaults)
+
+    # Load from pyproject.toml if it exists
+    pyproject_path = template_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        try:
+            with open(pyproject_path, "rb") as f:
+                pyproject_data = tomllib.load(f)
+
+            # Extract the agent-starter-pack configuration
+            toml_config = pyproject_data.get("tool", {}).get("agent-starter-pack", {})
+
+            # Fallback to [project] fields if not specified in agent-starter-pack section
+            project_info = pyproject_data.get("project", {})
+
+            # Apply pyproject.toml configuration (overrides defaults)
+            if toml_config:
+                config.update(toml_config)
+
+            # Apply [project] fallbacks if not already set
+            if "name" not in toml_config and "name" in project_info:
+                config["name"] = project_info["name"]
+
+            if "description" not in toml_config and "description" in project_info:
+                config["description"] = project_info["description"]
+
+            logging.debug(f"Loaded template config from {pyproject_path}")
+        except Exception as e:
+            logging.error(f"Error loading pyproject.toml config: {e}")
+
+    # Apply CLI overrides (highest precedence) using deep merge
+    if cli_overrides:
+        config = merge_template_configs(config, cli_overrides)
+        logging.debug(f"Applied CLI overrides: {cli_overrides}")
+
+    return config
 
 
 def get_base_template_name(config: dict[str, Any]) -> str:

src/cli/utils/template.py

@@ -445,6 +445,7 @@ def process_template(
     output_dir: pathlib.Path | None = None,
     remote_template_path: pathlib.Path | None = None,
     remote_config: dict[str, Any] | None = None,
+    in_folder: bool = False,
 ) -> None:
     """Process the template directory and create a new project.
 
@@ -460,6 +461,7 @@ def process_template(
         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
+        in_folder: Whether to template directly into the output directory instead of creating a subdirectory
     """
     logging.debug(f"Processing template from {template_dir}")
     logging.debug(f"Project name: {project_name}")
@@ -689,112 +691,228 @@ def process_template(
             logging.debug("Template processing completed successfully")
 
             # Move the generated project to the final destination
-            output_dir = temp_path / project_name
-            final_destination = destination_dir / project_name
-
-            logging.debug(f"Moving project from {output_dir} to {final_destination}")
-
-            if output_dir.exists():
-                if final_destination.exists():
-                    shutil.rmtree(final_destination)
-                shutil.copytree(output_dir, final_destination, dirs_exist_ok=True)
-                logging.debug(f"Project successfully created at {final_destination}")
-
-                # Render and merge Makefiles.
-                # If it's a local template, remote_template_path will be None,
-                # and only the base Makefile will be rendered.
-                render_and_merge_makefiles(
-                    base_template_path=base_template_path,
-                    final_destination=final_destination,
-                    cookiecutter_config=cookiecutter_config,
-                    remote_template_path=remote_template_path,
+            generated_project_dir = temp_path / project_name
+
+            if in_folder:
+                # For in-folder mode, copy files directly to the destination directory
+                final_destination = destination_dir
+                logging.debug(
+                    f"In-folder mode: copying files from {generated_project_dir} to {final_destination}"
                 )
 
-                # Delete appropriate files based on ADK tag
-                if "adk" in tags:
-                    files_to_delete = [final_destination / f for f in NON_ADK_FILES]
-                else:
-                    files_to_delete = [final_destination / f for f in ADK_FILES]
-
-                for file_path in files_to_delete:
-                    if file_path.exists():
-                        file_path.unlink()
-                        logging.debug(f"Deleted {file_path}")
-
-                # Clean up unused_* files and directories created by conditional templates
-                import glob
-
-                unused_patterns = [
-                    final_destination / "unused_*",
-                    final_destination / "**" / "unused_*",
-                ]
-
-                for pattern in unused_patterns:
-                    for unused_path_str in glob.glob(str(pattern), recursive=True):
-                        unused_path = pathlib.Path(unused_path_str)
-                        if unused_path.exists():
-                            if unused_path.is_dir():
-                                shutil.rmtree(unused_path)
+                if generated_project_dir.exists():
+                    # Copy all files from generated project to destination directory
+                    for item in generated_project_dir.iterdir():
+                        dest_item = final_destination / item.name
+
+                        # Special handling for README files - always preserve existing README
+                        # Special handling for pyproject.toml files - only preserve for in-folder updates
+                        should_preserve_file = item.name.lower().startswith(
+                            "readme"
+                        ) or (item.name == "pyproject.toml" and in_folder)
+                        if (
+                            should_preserve_file
+                            and (final_destination / item.name).exists()
+                        ):
+                            # The existing file stays, use base template file with starter_pack prefix
+                            base_name = item.stem
+                            extension = item.suffix
+                            dest_item = (
+                                final_destination
+                                / f"starter_pack_{base_name}{extension}"
+                            )
+
+                            # Try to use base template file instead of templated file
+                            base_file = base_template_path / item.name
+                            if base_file.exists():
                                 logging.debug(
-                                    f"Deleted unused directory: {unused_path}"
+                                    f"{item.name} conflict: preserving existing {item.name}, using base template {item.name} as starter_pack_{base_name}{extension}"
                                 )
+                                # Process the base template file through cookiecutter
+                                try:
+                                    import tempfile as tmp_module
+
+                                    with (
+                                        tmp_module.TemporaryDirectory() as temp_file_dir
+                                    ):
+                                        temp_file_path = pathlib.Path(temp_file_dir)
+
+                                        # Create a minimal cookiecutter structure for just the file
+                                        file_template_dir = (
+                                            temp_file_path / "file_template"
+                                        )
+                                        file_template_dir.mkdir()
+                                        file_project_dir = (
+                                            file_template_dir
+                                            / "{{cookiecutter.project_name}}"
+                                        )
+                                        file_project_dir.mkdir()
+
+                                        # Copy base file to template structure
+                                        shutil.copy2(
+                                            base_file, file_project_dir / item.name
+                                        )
+
+                                        # Create cookiecutter.json with same config as main template
+                                        with open(
+                                            file_template_dir / "cookiecutter.json",
+                                            "w",
+                                            encoding="utf-8",
+                                        ) as f:
+                                            json.dump(cookiecutter_config, f, indent=4)
+
+                                        # Process the file template
+                                        cookiecutter(
+                                            str(file_template_dir),
+                                            no_input=True,
+                                            overwrite_if_exists=True,
+                                            output_dir=str(temp_file_path),
+                                            extra_context={
+                                                "project_name": project_name,
+                                                "agent_name": agent_name,
+                                            },
+                                        )
+
+                                        # Copy the processed file
+                                        processed_file = (
+                                            temp_file_path / project_name / item.name
+                                        )
+                                        if processed_file.exists():
+                                            shutil.copy2(processed_file, dest_item)
+                                        else:
+                                            # Fallback to original behavior if processing fails
+                                            shutil.copy2(item, dest_item)
+
+                                except Exception as e:
+                                    logging.warning(
+                                        f"Failed to process base template {item.name}: {e}. Using templated {item.name} instead."
+                                    )
+                                    shutil.copy2(item, dest_item)
                             else:
-                                unused_path.unlink()
-                                logging.debug(f"Deleted unused file: {unused_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:
-                    # For local templates, use the existing logic
-                    lock_path = (
-                        pathlib.Path(__file__).parent.parent.parent.parent
-                        / "src"
-                        / "resources"
-                        / "locks"
-                        / f"uv-{agent_name}-{deployment_target}.lock"
-                    )
-                    logging.debug(f"Looking for lock file at: {lock_path}")
-                    logging.debug(f"Lock file exists: {lock_path.exists()}")
-                    if not lock_path.exists():
-                        raise FileNotFoundError(f"Lock file not found: {lock_path}")
-                    # Copy and rename to uv.lock in the project directory
-                    shutil.copy2(lock_path, final_destination / "uv.lock")
+                                # Fallback to original behavior if base file doesn't exist
+                                logging.debug(
+                                    f"{item.name} conflict: preserving existing {item.name}, saving templated {item.name} as starter_pack_{base_name}{extension}"
+                                )
+                                shutil.copy2(item, dest_item)
+                        else:
+                            # Normal file copying
+                            if item.is_dir():
+                                if dest_item.exists():
+                                    shutil.rmtree(dest_item)
+                                shutil.copytree(item, dest_item, dirs_exist_ok=True)
+                            else:
+                                shutil.copy2(item, dest_item)
                     logging.debug(
-                        f"Copied lock file from {lock_path} to {final_destination}/uv.lock"
+                        f"Project files successfully copied to {final_destination}"
                     )
+            else:
+                # Standard mode: create project subdirectory
+                final_destination = destination_dir / project_name
+                logging.debug(
+                    f"Standard mode: moving project from {generated_project_dir} to {final_destination}"
+                )
 
-                    # Replace cookiecutter project name with actual project name in lock file
-                    lock_file_path = final_destination / "uv.lock"
-                    with open(lock_file_path, "r+", encoding="utf-8") as f:
-                        content = f.read()
-                        f.seek(0)
-                        f.write(
-                            content.replace(
-                                "{{cookiecutter.project_name}}", project_name
-                            )
-                        )
-                        f.truncate()
+                if generated_project_dir.exists():
+                    if final_destination.exists():
+                        shutil.rmtree(final_destination)
+                    shutil.copytree(
+                        generated_project_dir, final_destination, dirs_exist_ok=True
+                    )
                     logging.debug(
-                        f"Updated project name in lock file at {lock_file_path}"
+                        f"Project successfully created at {final_destination}"
                     )
-            else:
-                logging.error(f"Generated project directory not found at {output_dir}")
+
+            # Always check if the project was successfully created before proceeding
+            if not final_destination.exists():
+                logging.error(
+                    f"Final destination directory not found at {final_destination}"
+                )
                 raise FileNotFoundError(
-                    f"Generated project directory not found at {output_dir}"
+                    f"Final destination directory not found at {final_destination}"
+                )
+
+            # Render and merge Makefiles.
+            # If it's a local template, remote_template_path will be None,
+            # and only the base Makefile will be rendered.
+            render_and_merge_makefiles(
+                base_template_path=base_template_path,
+                final_destination=final_destination,
+                cookiecutter_config=cookiecutter_config,
+                remote_template_path=remote_template_path,
+            )
+
+            # Delete appropriate files based on ADK tag
+            if "adk" in tags:
+                files_to_delete = [final_destination / f for f in NON_ADK_FILES]
+            else:
+                files_to_delete = [final_destination / f for f in ADK_FILES]
+
+            for file_path in files_to_delete:
+                if file_path.exists():
+                    file_path.unlink()
+                    logging.debug(f"Deleted {file_path}")
+
+            # Clean up unused_* files and directories created by conditional templates
+            import glob
+
+            unused_patterns = [
+                final_destination / "unused_*",
+                final_destination / "**" / "unused_*",
+            ]
+
+            for pattern in unused_patterns:
+                for unused_path_str in glob.glob(str(pattern), recursive=True):
+                    unused_path = pathlib.Path(unused_path_str)
+                    if unused_path.exists():
+                        if unused_path.is_dir():
+                            shutil.rmtree(unused_path)
+                            logging.debug(f"Deleted unused directory: {unused_path}")
+                        else:
+                            unused_path.unlink()
+                            logging.debug(f"Deleted unused file: {unused_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:
+                # For local templates, use the existing logic
+                lock_path = (
+                    pathlib.Path(__file__).parent.parent.parent.parent
+                    / "src"
+                    / "resources"
+                    / "locks"
+                    / f"uv-{agent_name}-{deployment_target}.lock"
                 )
+                logging.debug(f"Looking for lock file at: {lock_path}")
+                logging.debug(f"Lock file exists: {lock_path.exists()}")
+                if not lock_path.exists():
+                    raise FileNotFoundError(f"Lock file not found: {lock_path}")
+                # Copy and rename to uv.lock in the project directory
+                shutil.copy2(lock_path, final_destination / "uv.lock")
+                logging.debug(
+                    f"Copied lock file from {lock_path} to {final_destination}/uv.lock"
+                )
+
+                # Replace cookiecutter project name with actual project name in lock file
+                lock_file_path = final_destination / "uv.lock"
+                with open(lock_file_path, "r+", encoding="utf-8") as f:
+                    content = f.read()
+                    f.seek(0)
+                    f.write(
+                        content.replace("{{cookiecutter.project_name}}", project_name)
+                    )
+                    f.truncate()
+                logging.debug(f"Updated project name in lock file at {lock_file_path}")
 
         except Exception as e:
             logging.error(f"Failed to process template: {e!s}")

src/deployment_targets/agent_engine/app/agent_engine_app.py

@@ -208,6 +208,7 @@ def deploy_agent_engine_app(
     requirements_file: str = ".requirements.txt",
     extra_packages: list[str] = ["./app"],
     env_vars: dict[str, str] = {},
+    service_account: str | None = None,
 ) -> agent_engines.AgentEngine:
     """Deploy the agent engine app to Vertex AI."""
 
@@ -247,6 +248,7 @@ def deploy_agent_engine_app(
         "description": "{{cookiecutter.agent_description}}",
         "extra_packages": extra_packages,
         "env_vars": env_vars,
+        "service_account": service_account,
     }
     logging.info(f"Agent config: {agent_config}")
     agent_config["requirements"] = requirements
@@ -310,6 +312,11 @@ if __name__ == "__main__":
         "--set-env-vars",
         help="Comma-separated list of environment variables in KEY=VALUE format",
     )
+    parser.add_argument(
+        "--service-account",
+        default=None,
+        help="Service account email to use for the agent engine",
+    )
     args = parser.parse_args()
 
     # Parse environment variables if provided
@@ -337,4 +344,5 @@ if __name__ == "__main__":
         requirements_file=args.requirements_file,
         extra_packages=args.extra_packages,
         env_vars=env_vars,
+        service_account=args.service_account,
     )

src/deployment_targets/cloud_run/app/server.py

@@ -157,7 +157,7 @@ def stream_messages(
     set_tracing_properties(config)
     input_dict = input.model_dump()
 
-    for data in agent.stream(input_dict, config=config, stream_mode="messages"):
+    for data in agent.stream(input_dict, config=config, stream_mode="messages"):  # type: ignore[arg-type]
         yield dumps(data) + "\n"
 
 

src/deployment_targets/cloud_run/deployment/terraform/dev/service.tf

@@ -193,7 +193,7 @@ resource "google_cloud_run_v2_service" "app" {
 {%- endif %}
     }
 
-    service_account = google_service_account.cloud_run_app_sa.email
+    service_account = google_service_account.app_sa.email
     max_instance_request_concurrency = 40
 
     scaling {

src/deployment_targets/cloud_run/deployment/terraform/service.tf

@@ -216,7 +216,7 @@ resource "google_cloud_run_v2_service" "app_staging" {
 {%- endif %}
     }
 
-    service_account                = google_service_account.cloud_run_app_sa["staging"].email
+    service_account                = google_service_account.app_sa["staging"].email
     max_instance_request_concurrency = 40
 
     scaling {
@@ -322,7 +322,7 @@ resource "google_cloud_run_v2_service" "app_prod" {
 {%- endif %}
     }
 
-    service_account                = google_service_account.cloud_run_app_sa["prod"].email
+    service_account                = google_service_account.app_sa["prod"].email
     max_instance_request_concurrency = 40
 
     scaling {