agent-starter-pack 0.11.2__py3-none-any.whl → 0.12.1__py3-none-any.whl

src/base_template/{% if cookiecutter.cicd_runner == 'google_cloud_build' %}.cloudbuild{% else %}unused_.cloudbuild{% endif %}/staging.yaml

@@ -108,7 +108,7 @@ steps:
       - "-c"
       - |
         uv export --no-hashes --no-sources --no-header --no-dev --no-emit-project --no-annotate --locked > .requirements.txt
-        uv run app/agent_engine_app.py \
+        uv run {{cookiecutter.agent_directory}}/agent_engine_app.py \
           --project ${_STAGING_PROJECT_ID} \
           --location ${_REGION} \
           --service-account ${_APP_SA_EMAIL_STAGING} \

src/cli/commands/create.py

@@ -18,12 +18,17 @@ import os
 import pathlib
 import shutil
 import subprocess
+import sys
 import tempfile
 from collections.abc import Callable
 
 import click
-import tomllib
 from click.core import ParameterSource
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 from rich.console import Console
 from rich.prompt import IntPrompt, Prompt
 
@@ -101,6 +106,11 @@ def shared_template_options(f: Callable) -> Callable:
         type=click.Choice(["agent_engine", "cloud_run"]),
         help="Deployment target name",
     )(f)
+    f = click.option(
+        "--agent-directory",
+        "-dir",
+        help="Name of the agent directory (overrides template default)",
+    )(f)
     return f
 
 
@@ -232,8 +242,10 @@ def create(
     region: str,
     skip_checks: bool,
     in_folder: bool,
+    agent_directory: str | None,
     base_template: str | None = None,
     skip_welcome: bool = False,
+    cli_overrides: dict | None = None,
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
     try:
@@ -434,6 +446,14 @@ def create(
                 / ".template"
             )
             config = load_template_config(template_path)
+
+            # Apply CLI overrides for local templates if provided (e.g., from enhance command)
+            if cli_overrides:
+                config = merge_template_configs(config, cli_overrides)
+                if debug:
+                    logging.debug(
+                        f"Applied CLI overrides to local template config: {cli_overrides}"
+                    )
         # Data ingestion and datastore selection
         if include_data_ingestion or datastore:
             include_data_ingestion = True
@@ -610,6 +630,13 @@ def create(
         if debug:
             logging.debug(f"Output directory: {destination_dir}")
 
+        # Construct CLI overrides for template processing
+        final_cli_overrides = cli_overrides or {}
+        if agent_directory:
+            if "settings" not in final_cli_overrides:
+                final_cli_overrides["settings"] = {}
+            final_cli_overrides["settings"]["agent_directory"] = agent_directory
+
         try:
             # Process template (handles both local and remote templates)
             process_template(
@@ -623,8 +650,9 @@ def create(
                 session_type=final_session_type,
                 output_dir=destination_dir,
                 remote_template_path=template_source_path,
-                remote_config=config if template_source_path else None,
+                remote_config=config,
                 in_folder=in_folder,
+                cli_overrides=final_cli_overrides,
             )
 
             # Replace region in all files if a different region was specified

src/cli/commands/enhance.py

@@ -13,11 +13,18 @@
 # limitations under the License.
 
 import pathlib
+import sys
+from typing import Any
 
 import click
 from rich.console import Console
 from rich.prompt import IntPrompt
 
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
 from ..utils.logging import display_welcome_banner, handle_cli_error
 from ..utils.template import get_available_agents
 from .create import (
@@ -48,7 +55,7 @@ def display_base_template_selection(current_base: str) -> str:
     choice_num = 1
     current_choice = None
 
-    for _num, agent in agents.items():
+    for agent in agents.values():
         template_choices[choice_num] = agent["name"]
         current_indicator = " (current)" if agent["name"] == current_base else ""
         console.print(
@@ -89,6 +96,10 @@ def display_base_template_selection(current_base: str) -> str:
     "--base-template",
     help="Base template to inherit from (e.g., adk_base, langgraph_base_react, agentic_rag)",
 )
+@click.option(
+    "--agent-directory",
+    help="Custom directory name for agent files (default: 'app' or auto-detected from pyproject.toml)",
+)
 @shared_template_options
 @handle_cli_error
 def enhance(
@@ -105,6 +116,7 @@ def enhance(
     region: str,
     skip_checks: bool,
     base_template: str | None,
+    agent_directory: str | None,
 ) -> None:
     """Enhance your existing project with AI agent capabilities.
 
@@ -113,7 +125,8 @@ def enhance(
     creating a new project directory.
 
     For best compatibility, your project should follow the agent-starter-pack structure
-    with agent code organized in an /app folder (containing agent.py, etc.).
+    with agent code organized in an agent directory (default: /app, configurable via
+    --agent-directory).
 
     TEMPLATE_PATH can be:
     - A local directory path (e.g., . for current directory)
@@ -191,10 +204,13 @@ def enhance(
             load_remote_template_config,
         )
 
-        # Prepare CLI overrides for base template
-        cli_overrides = {}
+        # Prepare CLI overrides for base template and agent directory
+        cli_overrides: dict[str, Any] = {}
         if base_template:
             cli_overrides["base_template"] = base_template
+        if agent_directory:
+            cli_overrides["settings"] = cli_overrides.get("settings", {})
+            cli_overrides["settings"]["agent_directory"] = agent_directory
 
         # Load config from current directory for inheritance info
         current_dir = pathlib.Path.cwd()
@@ -209,6 +225,10 @@ def enhance(
             if selected_base_template != original_base_template_name:
                 # Update CLI overrides with the selected base template
                 cli_overrides["base_template"] = selected_base_template
+                # Preserve agent_directory override if it was set
+                if agent_directory:
+                    cli_overrides["settings"] = cli_overrides.get("settings", {})
+                    cli_overrides["settings"]["agent_directory"] = agent_directory
                 base_template = selected_base_template
                 console.print(
                     f"✅ Selected base template: [cyan]{selected_base_template}[/cyan]"
@@ -232,9 +252,51 @@ def enhance(
     # Validate project structure when using current directory template
     if template_path == pathlib.Path("."):
         current_dir = pathlib.Path.cwd()
-        app_folder = current_dir / "app"
 
-        if not app_folder.exists() or not app_folder.is_dir():
+        # Determine agent directory: CLI param > pyproject.toml detection > default
+        detected_agent_directory = "app"  # default
+        if not agent_directory:  # Only try to detect if not provided via CLI
+            pyproject_path = current_dir / "pyproject.toml"
+            if pyproject_path.exists():
+                try:
+                    with open(pyproject_path, "rb") as f:
+                        pyproject_data = tomllib.load(f)
+                    packages = (
+                        pyproject_data.get("tool", {})
+                        .get("hatch", {})
+                        .get("build", {})
+                        .get("targets", {})
+                        .get("wheel", {})
+                        .get("packages", [])
+                    )
+                    if packages:
+                        # Find the first package that isn't 'frontend'
+                        for pkg in packages:
+                            if pkg != "frontend":
+                                detected_agent_directory = pkg
+                                break
+                except Exception as e:
+                    if debug:
+                        console.print(
+                            f"[dim]Could not auto-detect agent directory: {e}[/dim]"
+                        )
+                    pass  # Fall back to default
+
+        final_agent_directory = agent_directory or detected_agent_directory
+
+        # Show info about agent directory selection
+        if agent_directory:
+            console.print(
+                f"ℹ️  Using CLI-specified agent directory: [cyan]{agent_directory}[/cyan]"
+            )
+        elif detected_agent_directory != "app":
+            console.print(
+                f"ℹ️  Auto-detected agent directory: [cyan]{detected_agent_directory}[/cyan]"
+            )
+
+        agent_folder = current_dir / final_agent_directory
+
+        if not agent_folder.exists() or not agent_folder.is_dir():
             console.print()
             console.print(
                 "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -245,42 +307,61 @@ def enhance(
             )
             console.print()
             console.print(
-                "📁 [bold]Expected Structure:[/bold] [cyan]/app[/cyan] folder containing your agent code"
+                f"📁 [bold]Expected Structure:[/bold] [cyan]/{final_agent_directory}[/cyan] folder containing your agent code"
             )
             console.print(f"📍 [bold]Current Directory:[/bold] {current_dir}")
-            console.print("❌ [bold red]Missing:[/bold red] /app folder")
+            console.print(
+                f"❌ [bold red]Missing:[/bold red] /{final_agent_directory} folder"
+            )
             console.print()
             console.print(
-                "[dim]The enhance command can still proceed, but for best compatibility"
-                " your agent code should be organized in an /app folder structure.[/dim]"
+                f"The enhance command can still proceed, but for best compatibility"
+                f" your agent code should be organized in a /{final_agent_directory} folder structure."
             )
             console.print()
 
             # Ask for confirmation after showing the structure warning
+            console.print("💡 Options:")
             console.print(
-                "💡 [dim]Consider creating an /app folder for better compatibility.[/dim]"
+                f"   • Create a /{final_agent_directory} folder and move your agent code there"
             )
+            if final_agent_directory == "app":
+                console.print(
+                    "   • Use [cyan]--agent-directory <custom_name>[/cyan] if your agent code is in a different directory"
+                )
+            else:
+                console.print(
+                    "   • Use [cyan]--agent-directory <custom_name>[/cyan] to specify your existing agent directory"
+                )
             console.print()
 
             if not auto_approve:
                 if not click.confirm(
-                    "Continue with enhancement despite missing /app folder?",
+                    f"Continue with enhancement despite missing /{final_agent_directory} folder?",
                     default=True,
                 ):
                     console.print("✋ [yellow]Enhancement cancelled.[/yellow]")
                     return
         else:
             # Check for common agent files
-            agent_py = app_folder / "agent.py"
+            agent_py = agent_folder / "agent.py"
             if agent_py.exists():
                 console.print(
-                    "Detected existing agent structure with [cyan]/app/agent.py[/cyan]"
+                    f"Detected existing agent structure with [cyan]/{final_agent_directory}/agent.py[/cyan]"
                 )
             else:
                 console.print(
-                    "ℹ️  [blue]Found /app folder[/blue] - ensure your agent code is properly organized within it"
+                    f"ℹ️  [blue]Found /{final_agent_directory} folder[/blue] - ensure your agent code is properly organized within it, including an agent.py file"
                 )
 
+    # Prepare CLI overrides to pass to create command
+    final_cli_overrides: dict[str, Any] = {}
+    if base_template:
+        final_cli_overrides["base_template"] = base_template
+    if agent_directory:
+        final_cli_overrides["settings"] = final_cli_overrides.get("settings", {})
+        final_cli_overrides["settings"]["agent_directory"] = agent_directory
+
     # Call the create command with in-folder mode enabled
     ctx.invoke(
         create,
@@ -297,6 +378,8 @@ def enhance(
         region=region,
         skip_checks=skip_checks,
         in_folder=True,  # Always use in-folder mode for enhance
+        agent_directory=agent_directory,
         base_template=base_template,
         skip_welcome=True,  # Skip welcome message since enhance shows its own
+        cli_overrides=final_cli_overrides if final_cli_overrides else None,
     )

src/cli/commands/list.py

@@ -14,9 +14,14 @@
 
 import logging
 import pathlib
+import sys
 
 import click
-import tomllib
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 from rich.console import Console
 from rich.table import Table
 

src/cli/utils/remote_template.py

@@ -18,11 +18,15 @@ import pathlib
 import re
 import shutil
 import subprocess
+import sys
 import tempfile
 from dataclasses import dataclass
 from typing import Any
 
-import tomllib
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
 from jinja2 import Environment
 
 

src/cli/utils/template.py

@@ -34,9 +34,6 @@ from .remote_template import (
     render_and_merge_makefiles,
 )
 
-ADK_FILES = ["app/__init__.py"]
-NON_ADK_FILES: list[str] = []
-
 
 @dataclass
 class TemplateConfig:
@@ -72,7 +69,11 @@ class TemplateConfig:
             raise ValueError(f"Error loading template config: {err}") from err
 
 
-OVERWRITE_FOLDERS = ["app", "frontend", "tests", "notebooks"]
+def get_overwrite_folders(agent_directory: str) -> list[str]:
+    """Get folders to overwrite with configurable agent directory."""
+    return [agent_directory, "frontend", "tests", "notebooks"]
+
+
 TEMPLATE_CONFIG_FILE = "templateconfig.yaml"
 DEPLOYMENT_FOLDERS = ["cloud_run", "agent_engine"]
 DEFAULT_FRONTEND = "streamlit"
@@ -446,6 +447,7 @@ def process_template(
     remote_template_path: pathlib.Path | None = None,
     remote_config: dict[str, Any] | None = None,
     in_folder: bool = False,
+    cli_overrides: dict[str, Any] | None = None,
 ) -> None:
     """Process the template directory and create a new project.
 
@@ -462,12 +464,25 @@ def process_template(
         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
+        cli_overrides: Optional CLI override values that should take precedence over template config
     """
     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}")
 
+    def get_agent_directory(
+        template_config: dict[str, Any], cli_overrides: dict[str, Any] | None = None
+    ) -> str:
+        """Get agent directory with CLI override support."""
+        if (
+            cli_overrides
+            and "settings" in cli_overrides
+            and "agent_directory" in cli_overrides["settings"]
+        ):
+            return cli_overrides["settings"]["agent_directory"]
+        return template_config.get("settings", {}).get("agent_directory", "app")
+
     # Handle remote vs local templates
     is_remote = remote_template_path is not None
 
@@ -519,7 +534,21 @@ def process_template(
             base_template_path = (
                 pathlib.Path(__file__).parent.parent.parent / "base_template"
             )
-            copy_files(base_template_path, project_template, agent_name, overwrite=True)
+            # Get agent directory from config early for use in file copying
+            # Load config early to get agent_directory
+            if is_remote:
+                early_config = remote_config or {}
+            else:
+                template_path = pathlib.Path(template_dir)
+                early_config = load_template_config(template_path)
+            agent_directory = get_agent_directory(early_config, cli_overrides)
+            copy_files(
+                base_template_path,
+                project_template,
+                agent_name,
+                overwrite=True,
+                agent_directory=agent_directory,
+            )
             logging.debug(f"1. Copied base template from {base_template_path}")
 
             # 2. Process deployment target if specified
@@ -535,6 +564,7 @@ def process_template(
                         project_template,
                         agent_name=agent_name,
                         overwrite=True,
+                        agent_directory=agent_directory,
                     )
                     logging.debug(
                         f"2. Processed deployment files for target: {deployment_target}"
@@ -556,27 +586,11 @@ def process_template(
             copy_frontend_files(frontend_type, project_template)
             logging.debug(f"4. Processed frontend files for type: {frontend_type}")
 
-            # 5. Copy agent-specific files to override base template
-            if agent_path.exists():
-                for folder in OVERWRITE_FOLDERS:
-                    agent_folder = agent_path / folder
-                    project_folder = project_template / folder
-                    if agent_folder.exists():
-                        logging.debug(f"5. Copying agent folder {folder} with override")
-                        copy_files(
-                            agent_folder, project_folder, agent_name, overwrite=True
-                        )
-
-            # 6. Finally, overlay remote template files if present
+            # 6. Skip remote template files during cookiecutter processing
+            # Remote files will be copied after cookiecutter to avoid Jinja conflicts
             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,
+                    "6. Skipping remote template files during cookiecutter processing - will copy after templating"
                 )
 
             # Load and validate template config first
@@ -602,6 +616,45 @@ def process_template(
             # Use the already loaded config
             template_config = config
 
+            # 5. Copy agent-specific files to override base template (using final config)
+            if agent_path.exists():
+                agent_directory = get_agent_directory(template_config, cli_overrides)
+
+                # Get the template's default agent directory (usually "app")
+                template_agent_directory = template_config.get("settings", {}).get(
+                    "agent_directory", "app"
+                )
+
+                # Copy agent directory (always from "app" to target directory)
+                source_agent_folder = agent_path / template_agent_directory
+                target_agent_folder = project_template / agent_directory
+                if source_agent_folder.exists():
+                    logging.debug(
+                        f"5. Copying agent folder {template_agent_directory} -> {agent_directory} with override"
+                    )
+                    copy_files(
+                        source_agent_folder,
+                        target_agent_folder,
+                        agent_name,
+                        overwrite=True,
+                        agent_directory=agent_directory,
+                    )
+
+                # Copy other folders (frontend, tests, notebooks)
+                other_folders = ["frontend", "tests", "notebooks"]
+                for folder in other_folders:
+                    agent_folder = agent_path / folder
+                    project_folder = project_template / folder
+                    if agent_folder.exists():
+                        logging.debug(f"5. Copying {folder} folder with override")
+                        copy_files(
+                            agent_folder,
+                            project_folder,
+                            agent_name,
+                            overwrite=True,
+                            agent_directory=agent_directory,
+                        )
+
             # Check if data processing should be included
             if include_data_ingestion and datastore:
                 logging.debug(
@@ -649,6 +702,7 @@ def process_template(
                 "extra_dependencies": [extra_deps],
                 "data_ingestion": include_data_ingestion,
                 "datastore_type": datastore if datastore else "",
+                "agent_directory": get_agent_directory(template_config, cli_overrides),
                 "adk_cheatsheet": adk_cheatsheet_content,
                 "llm_txt": llm_txt_content,
                 "_copy_without_render": [
@@ -664,7 +718,9 @@ def process_template(
                     "*templates.py",  # Don't render templates files
                     "Makefile",  # Don't render Makefile - handled by render_and_merge_makefiles
                     # Don't render agent.py unless it's agentic_rag
-                    "app/agent.py" if agent_name != "agentic_rag" else "",
+                    f"{get_agent_directory(template_config, cli_overrides)}/agent.py"
+                    if agent_name != "agentic_rag"
+                    else "",
                 ],
             }
 
@@ -690,6 +746,21 @@ def process_template(
             )
             logging.debug("Template processing completed successfully")
 
+            # Now overlay remote template files if present (after cookiecutter processing)
+            if is_remote and remote_template_path:
+                generated_project_dir = temp_path / project_name
+                logging.debug(
+                    f"Copying remote template files from {remote_template_path} to {generated_project_dir}"
+                )
+                copy_files(
+                    remote_template_path,
+                    generated_project_dir,
+                    agent_name=agent_name,
+                    overwrite=True,
+                    agent_directory=agent_directory,
+                )
+                logging.debug("Remote template files copied successfully")
+
             # Move the generated project to the final destination
             generated_project_dir = temp_path / project_name
 
@@ -842,15 +913,7 @@ def process_template(
             )
 
             # 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}")
+            agent_directory = get_agent_directory(template_config, cli_overrides)
 
             # Clean up unused_* files and directories created by conditional templates
             import glob
@@ -923,11 +986,15 @@ def process_template(
             os.chdir(original_dir)
 
 
-def should_exclude_path(path: pathlib.Path, agent_name: str) -> bool:
+def should_exclude_path(
+    path: pathlib.Path, agent_name: str, agent_directory: str = "app"
+) -> bool:
     """Determine if a path should be excluded based on the agent type."""
     if agent_name == "live_api":
-        # Exclude the unit test utils folder and app/utils folder for live_api
-        if "tests/unit/test_utils" in str(path) or "app/utils" in str(path):
+        # Exclude the unit test utils folder and agent utils folder for live_api
+        if "tests/unit/test_utils" in str(path) or f"{agent_directory}/utils" in str(
+            path
+        ):
             logging.debug(f"Excluding path for live_api: {path}")
             return True
     return False
@@ -938,6 +1005,7 @@ def copy_files(
     dst: pathlib.Path,
     agent_name: str | None = None,
     overwrite: bool = False,
+    agent_directory: str = "app",
 ) -> None:
     """
     Copy files with configurable behavior for exclusions and overwrites.
@@ -947,6 +1015,7 @@ def copy_files(
         dst: Destination path
         agent_name: Name of the agent (for agent-specific exclusions)
         overwrite: Whether to overwrite existing files (True) or skip them (False)
+        agent_directory: Name of the agent directory (for agent-specific exclusions)
     """
 
     def should_skip(path: pathlib.Path) -> bool:
@@ -957,7 +1026,9 @@ def copy_files(
             return True
         if ".git" in path.parts:
             return True
-        if agent_name is not None and should_exclude_path(path, agent_name):
+        if agent_name is not None and should_exclude_path(
+            path, agent_name, agent_directory
+        ):
             return True
         if path.is_dir() and path.name == ".template":
             return True
@@ -970,9 +1041,10 @@ def copy_files(
             if should_skip(item):
                 logging.debug(f"Skipping file/directory: {item}")
                 continue
+
             d = dst / item.name
             if item.is_dir():
-                copy_files(item, d, agent_name, overwrite)
+                copy_files(item, d, agent_name, overwrite, agent_directory)
             else:
                 if overwrite or not d.exists():
                     logging.debug(f"Copying file: {item} -> {d}")
@@ -1012,7 +1084,10 @@ def copy_frontend_files(frontend_type: str, project_template: pathlib.Path) -> N
 
 
 def copy_deployment_files(
-    deployment_target: str, agent_name: str, project_template: pathlib.Path
+    deployment_target: str,
+    agent_name: str,
+    project_template: pathlib.Path,
+    agent_directory: str = "app",
 ) -> None:
     """Copy files from the specified deployment target folder."""
     if not deployment_target:
@@ -1028,7 +1103,11 @@ def copy_deployment_files(
         logging.debug(f"Copying deployment files from {deployment_path}")
         # Pass agent_name to respect agent-specific exclusions
         copy_files(
-            deployment_path, project_template, agent_name=agent_name, overwrite=True
+            deployment_path,
+            project_template,
+            agent_name=agent_name,
+            overwrite=True,
+            agent_directory=agent_directory,
         )
     else:
         logging.warning(f"Deployment target directory not found: {deployment_path}")

src/deployment_targets/agent_engine/tests/integration/test_agent_engine_app.py

@@ -18,11 +18,11 @@ import pytest
 {%- if "adk" in cookiecutter.tags %}
 from google.adk.events.event import Event
 
-from app.agent import root_agent
-from app.agent_engine_app import AgentEngineApp
+from {{cookiecutter.agent_directory}}.agent import root_agent
+from {{cookiecutter.agent_directory}}.agent_engine_app import AgentEngineApp
 {%- else %}
 
-from app.agent_engine_app import AgentEngineApp
+from {{cookiecutter.agent_directory}}.agent_engine_app import AgentEngineApp
 {%- endif %}