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

src/cli/commands/create.py

@@ -12,21 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import datetime
 import logging
 import os
 import pathlib
 import shutil
 import subprocess
 import tempfile
+from collections.abc import Callable
 
 import click
+import tomllib
 from click.core import ParameterSource
 from rich.console import Console
 from rich.prompt import IntPrompt, Prompt
 
 from ..utils.datastores import DATASTORE_TYPES, DATASTORES
 from ..utils.gcp import verify_credentials, verify_vertex_connection
-from ..utils.logging import handle_cli_error
+from ..utils.logging import display_welcome_banner, handle_cli_error
 from ..utils.remote_template import (
     fetch_remote_template,
     get_base_template_name,
@@ -48,6 +51,114 @@ from ..utils.template import (
 
 console = Console()
 
+# Export the shared decorator for use by other commands
+__all__ = ["create", "shared_template_options"]
+
+
+def shared_template_options(f: Callable) -> Callable:
+    """Decorator to add shared options for template-based commands."""
+    # Apply options in reverse order since decorators are applied bottom-up
+    f = click.option(
+        "--skip-checks",
+        is_flag=True,
+        help="Skip verification checks for GCP and Vertex AI",
+        default=False,
+    )(f)
+    f = click.option(
+        "--region",
+        help="GCP region for deployment (default: us-central1)",
+        default="us-central1",
+    )(f)
+    f = click.option(
+        "--auto-approve", is_flag=True, help="Skip credential confirmation prompts"
+    )(f)
+    f = click.option("--debug", is_flag=True, help="Enable debug logging")(f)
+    f = click.option(
+        "--session-type",
+        type=click.Choice(["in_memory", "alloydb", "agent_engine"]),
+        help="Type of session storage to use",
+    )(f)
+    f = click.option(
+        "--datastore",
+        "-ds",
+        type=click.Choice(DATASTORE_TYPES),
+        help="Type of datastore to use for data ingestion (requires --include-data-ingestion)",
+    )(f)
+    f = click.option(
+        "--include-data-ingestion",
+        "-i",
+        is_flag=True,
+        help="Include data ingestion pipeline in the project",
+    )(f)
+    f = click.option(
+        "--cicd-runner",
+        type=click.Choice(["google_cloud_build", "github_actions"]),
+        help="CI/CD runner to use",
+    )(f)
+    f = click.option(
+        "--deployment-target",
+        "-d",
+        type=click.Choice(["agent_engine", "cloud_run"]),
+        help="Deployment target name",
+    )(f)
+    return f
+
+
+def get_available_base_templates() -> list[str]:
+    """Get list of available base templates for inheritance.
+
+    Returns:
+        List of base template names.
+    """
+    agents = get_available_agents()
+    return sorted([agent_info["name"] for agent_info in agents.values()])
+
+
+def validate_base_template(base_template: str) -> bool:
+    """Validate that a base template exists.
+
+    Args:
+        base_template: Name of the base template to validate
+
+    Returns:
+        True if the base template exists, False otherwise
+    """
+    available_templates = get_available_base_templates()
+    return base_template in available_templates
+
+
+def get_standard_ignore_patterns() -> Callable[[str, list[str]], list[str]]:
+    """Get standard ignore patterns for copying directories.
+
+    Returns:
+        A callable that can be used with shutil.copytree's ignore parameter.
+    """
+    exclude_dirs = {
+        ".git",
+        ".venv",
+        "venv",
+        "__pycache__",
+        ".pytest_cache",
+        "node_modules",
+        ".next",
+        "dist",
+        "build",
+        ".DS_Store",
+        ".vscode",
+        ".idea",
+        "*.egg-info",
+        ".mypy_cache",
+        ".coverage",
+        "htmlcov",
+        ".tox",
+        ".cache",
+    }
+
+    def ignore_patterns(dir: str, files: list[str]) -> list[str]:
+        return [f for f in files if f in exclude_dirs or f.startswith(".backup_")]
+
+    return ignore_patterns
+
 
 def normalize_project_name(project_name: str) -> str:
     """Normalize project name for better compatibility with cloud resources and tools."""
@@ -91,35 +202,6 @@ def normalize_project_name(project_name: str) -> str:
     "-a",
     help="Template identifier to use. Can be a local agent name (e.g., `chat_agent`), a local path (`local@/path/to/template`), an `adk-samples` shortcut (e.g., `adk@data-science`), or a remote Git URL. Both shorthand (e.g., `github.com/org/repo/path@main`) and full URLs from your browser (e.g., `https://github.com/org/repo/tree/main/path`) are supported. Lists available local templates if omitted.",
 )
-@click.option(
-    "--deployment-target",
-    "-d",
-    type=click.Choice(["agent_engine", "cloud_run"]),
-    help="Deployment target name",
-)
-@click.option(
-    "--cicd-runner",
-    type=click.Choice(["google_cloud_build", "github_actions"]),
-    help="CI/CD runner to use",
-)
-@click.option(
-    "--include-data-ingestion",
-    "-i",
-    is_flag=True,
-    help="Include data ingestion pipeline in the project",
-)
-@click.option(
-    "--datastore",
-    "-ds",
-    type=click.Choice(DATASTORE_TYPES),
-    help="Type of datastore to use for data ingestion (requires --include-data-ingestion)",
-)
-@click.option(
-    "--session-type",
-    type=click.Choice(["in_memory", "alloydb", "agent_engine"]),
-    help="Type of session storage to use",
-)
-@click.option("--debug", is_flag=True, help="Enable debug logging")
 @click.option(
     "--output-dir",
     "-o",
@@ -127,19 +209,13 @@ def normalize_project_name(project_name: str) -> str:
     help="Output directory for the project (default: current directory)",
 )
 @click.option(
-    "--auto-approve", is_flag=True, help="Skip credential confirmation prompts"
-)
-@click.option(
-    "--region",
-    help="GCP region for deployment (default: us-central1)",
-    default="us-central1",
-)
-@click.option(
-    "--skip-checks",
+    "--in-folder",
+    "-if",
     is_flag=True,
-    help="Skip verification checks for GCP and Vertex AI",
+    help="Template files directly into the current directory instead of creating a new project directory",
     default=False,
 )
+@shared_template_options
 @handle_cli_error
 def create(
     ctx: click.Context,
@@ -155,30 +231,15 @@ def create(
     auto_approve: bool,
     region: str,
     skip_checks: bool,
+    in_folder: bool,
+    base_template: str | None = None,
+    skip_welcome: bool = False,
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
     try:
-        # Display welcome banner
-        if 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 :rocket:===",
-                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"
-            )
+        # Display welcome banner (unless skipped)
+        if not skip_welcome:
+            display_welcome_banner(agent)
         # Validate project name
         if len(project_name) > 26:
             console.print(
@@ -199,14 +260,41 @@ def create(
         destination_dir = pathlib.Path(output_dir) if output_dir else pathlib.Path.cwd()
         destination_dir = destination_dir.resolve()  # Convert to absolute path
 
-        # Check if project would exist in output directory
-        project_path = destination_dir / project_name
-        if project_path.exists():
-            console.print(
-                f"Error: Project directory '{project_path}' already exists",
-                style="bold red",
-            )
-            return
+        if in_folder:
+            # For in-folder templating, use the current directory directly
+            project_path = destination_dir
+            # In-folder mode is permissive - we assume the user wants to enhance their existing repo
+
+            # Create backup of entire directory before in-folder templating
+            timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+            backup_dir = project_path / f".backup_{project_path.name}_{timestamp}"
+
+            console.print("📦 [blue]Creating backup before modification...[/blue]")
+
+            try:
+                shutil.copytree(
+                    project_path, backup_dir, ignore=get_standard_ignore_patterns()
+                )
+                console.print(f"Backup created: [cyan]{backup_dir.name}[/cyan]")
+            except Exception as e:
+                console.print(
+                    f"⚠️  [yellow]Warning: Could not create backup: {e}[/yellow]"
+                )
+                if not auto_approve:
+                    if not click.confirm("Continue without backup?", default=True):
+                        console.print("✋ [red]Operation cancelled.[/red]")
+                        return
+
+            console.print()
+        else:
+            # Check if project would exist in output directory
+            project_path = destination_dir / project_name
+            if project_path.exists():
+                console.print(
+                    f"Error: Project directory '{project_path}' already exists",
+                    style="bold red",
+                )
+                return
 
         # Agent selection - handle remote templates
         selected_agent = None
@@ -226,7 +314,11 @@ def create(
                 temp_dir = tempfile.mkdtemp(prefix="asp_local_template_")
                 temp_dir_to_clean = temp_dir
                 template_source_path = pathlib.Path(temp_dir) / local_path.name
-                shutil.copytree(local_path, template_source_path)
+                shutil.copytree(
+                    local_path,
+                    template_source_path,
+                    ignore=get_standard_ignore_patterns(),
+                )
 
                 selected_agent = f"local_{template_source_path.name}"
                 console.print(f"Using local template: {local_path}")
@@ -303,32 +395,25 @@ def create(
 
         # Load template configuration based on whether it's remote or local
         if template_source_path:
-            # Load remote template config
-            source_config = load_remote_template_config(template_source_path)
+            # Prepare CLI overrides for remote template config
+            cli_overrides = {}
+            if base_template:
+                cli_overrides["base_template"] = base_template
 
-            # Check if remote template has the required structure
-            template_config_path = (
-                template_source_path / ".template" / "templateconfig.yaml"
+            # Load remote template config
+            source_config = load_remote_template_config(
+                template_source_path, cli_overrides
             )
 
-            if not template_config_path.exists():
-                console.print(
-                    "Error: Template is invalid or improperly structured.",
-                    style="bold red",
-                )
-                console.print(
-                    "Templates must contain a '.template/templateconfig.yaml' file.\n\n"
-                    "Expected structure:\n"
-                    "  your-template/\n"
-                    "  └── .template/\n"
-                    "      ├── templateconfig.yaml\n"
-                    "      └── [other template files...]",
-                    style="yellow",
-                )
-                return
+            # Remote templates now work even without pyproject.toml thanks to defaults
+            if debug and source_config:
+                logging.debug(f"Final remote template config: {source_config}")
 
             # Load base template config for inheritance
             base_template_name = get_base_template_name(source_config)
+            if debug:
+                logging.debug(f"Using base template: {base_template_name}")
+
             base_template_path = (
                 pathlib.Path(__file__).parent.parent.parent.parent
                 / "agents"
@@ -539,6 +624,7 @@ def create(
                 output_dir=destination_dir,
                 remote_template_path=template_source_path,
                 remote_config=config if template_source_path else None,
+                in_folder=in_folder,
             )
 
             # Replace region in all files if a different region was specified
@@ -557,8 +643,12 @@ def create(
                         f"Failed to clean up temporary directory {temp_dir_to_clean}: {e}"
                     )
 
-        project_path = destination_dir / project_name
-        cd_path = project_path if output_dir else project_name
+        if not in_folder:
+            project_path = destination_dir / project_name
+            cd_path = project_path if output_dir else project_name
+        else:
+            project_path = destination_dir
+            cd_path = "."
 
         if include_data_ingestion:
             project_id = creds_info.get("project", "")
@@ -665,19 +755,31 @@ def display_adk_samples_selection() -> str:
         adk_agents = {}
         agent_count = 1
 
-        # Search for templateconfig.yaml files to identify agents
-        for config_path in sorted(repo_path.glob("**/templateconfig.yaml")):
+        # Search for pyproject.toml files to identify agents
+        for config_path in sorted(repo_path.glob("**/pyproject.toml")):
             try:
-                import yaml
+                with open(config_path, "rb") as f:
+                    pyproject_data = tomllib.load(f)
+
+                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
 
-                with open(config_path, encoding="utf-8") as f:
-                    config = yaml.safe_load(f)
+                template_root = config_path.parent
 
-                agent_name = config.get("name", config_path.parent.parent.name)
-                description = config.get("description", "No description available")
+                # 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 ""
+                )
 
                 # Get the relative path from repo root
-                relative_path = config_path.parent.parent.relative_to(repo_path)
+                relative_path = template_root.relative_to(repo_path)
 
                 # For adk-samples, use just the agent name for the spec
                 # This handles cases like python/agents/gemini-fullstack -> gemini-fullstack

src/cli/commands/enhance.py

@@ -0,0 +1,248 @@
+# 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 pathlib
+
+import click
+from rich.console import Console
+
+from ..utils.logging import display_welcome_banner, handle_cli_error
+from .create import (
+    create,
+    get_available_base_templates,
+    shared_template_options,
+    validate_base_template,
+)
+
+console = Console()
+
+
+@click.command()
+@click.pass_context
+@click.argument(
+    "template_path",
+    type=click.Path(path_type=pathlib.Path),
+    default=".",
+    required=False,
+)
+@click.option(
+    "--name",
+    "-n",
+    help="Project name for templating (defaults to current directory name)",
+)
+@click.option(
+    "--base-template",
+    help="Base template to inherit from (e.g., adk_base, langgraph_base_react, agentic_rag)",
+)
+@shared_template_options
+@handle_cli_error
+def enhance(
+    ctx: click.Context,
+    template_path: pathlib.Path,
+    name: str | None,
+    deployment_target: str | None,
+    cicd_runner: str | None,
+    include_data_ingestion: bool,
+    datastore: str | None,
+    session_type: str | None,
+    debug: bool,
+    auto_approve: bool,
+    region: str,
+    skip_checks: bool,
+    base_template: str | None,
+) -> None:
+    """Enhance your existing project with AI agent capabilities.
+
+    This command is an alias for 'create' with --in-folder mode enabled, designed to
+    add agent-starter-pack features to your existing project in-place rather than
+    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.).
+
+    TEMPLATE_PATH can be:
+    - A local directory path (e.g., . for current directory)
+    - An agent name (e.g., adk_base)
+    - A remote template (e.g., adk@data-science)
+
+    The command will validate your project structure and provide guidance if needed.
+    """
+
+    # Display welcome banner for enhance command
+    display_welcome_banner(enhance_mode=True)
+
+    # Validate base template if provided
+    if base_template and not validate_base_template(base_template):
+        available_templates = get_available_base_templates()
+        console.print(
+            f"Error: Base template '{base_template}' not found.", style="bold red"
+        )
+        console.print(
+            f"Available base templates: {', '.join(available_templates)}",
+            style="yellow",
+        )
+        return
+
+    # Determine project name
+    if name:
+        project_name = name
+    else:
+        # Use current directory name as default
+        current_dir = pathlib.Path.cwd()
+        project_name = current_dir.name
+        console.print(
+            f"Using current directory name as project name: {project_name}", style="dim"
+        )
+
+    # Show confirmation prompt for enhancement unless auto-approved
+    if not auto_approve:
+        current_dir = pathlib.Path.cwd()
+        console.print()
+        console.print(
+            "🚀 [blue]Ready to enhance your project with deployment capabilities[/blue]"
+        )
+        console.print(f"📂 {current_dir}")
+        console.print()
+        console.print("[bold]What will happen:[/bold]")
+        console.print("• New template files will be added to this directory")
+        console.print("• Your existing files will be preserved")
+        console.print("• A backup will be created before any changes")
+        console.print()
+
+        if not click.confirm(
+            f"Continue with enhancement? {click.style('[Y/n]: ', fg='blue', bold=True)}",
+            default=True,
+            show_default=False,
+        ):
+            console.print("✋ [yellow]Enhancement cancelled.[/yellow]")
+            return
+        console.print()
+
+    # Determine agent specification based on template_path
+    if template_path == pathlib.Path("."):
+        # Current directory - use local@ syntax
+        agent_spec = "local@."
+    elif template_path.is_dir():
+        # Other local directory
+        agent_spec = f"local@{template_path.resolve()}"
+    else:
+        # Assume it's an agent name or remote spec
+        agent_spec = str(template_path)
+
+    # Show base template inheritance info early for local projects
+    if agent_spec.startswith("local@"):
+        from ..utils.remote_template import (
+            get_base_template_name,
+            load_remote_template_config,
+        )
+
+        # Prepare CLI overrides for base template
+        cli_overrides = {}
+        if base_template:
+            cli_overrides["base_template"] = base_template
+
+        # Load config from current directory for inheritance info
+        current_dir = pathlib.Path.cwd()
+        source_config = load_remote_template_config(current_dir, cli_overrides)
+        base_template_name = get_base_template_name(source_config)
+
+        console.print()
+        console.print(
+            f"Template inherits from base: [cyan][link=https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/agents/{base_template_name}]{base_template_name}[/link][/cyan]"
+        )
+
+        # Show available alternatives and guidance
+        available_bases = get_available_base_templates()
+        if len(available_bases) > 1:
+            other_bases = [b for b in available_bases if b != base_template_name]
+            if other_bases:
+                console.print(
+                    f"[dim]💡 To use a different base template (e.g., {', '.join(other_bases[:2])}), use:[/dim]"
+                )
+                console.print(
+                    "[dim]   asp enhance . --base-template langgraph_base_react[/dim]"
+                )
+        console.print()
+
+    # 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():
+            console.print()
+            console.print(
+                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            )
+            console.print("⚠️  [bold yellow]PROJECT STRUCTURE WARNING[/bold yellow] ⚠️")
+            console.print(
+                "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            )
+            console.print()
+            console.print(
+                "📁 [bold]Expected Structure:[/bold] [cyan]/app[/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()
+            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]"
+            )
+            console.print()
+
+            # Ask for confirmation after showing the structure warning
+            console.print(
+                "💡 [dim]Consider creating an /app folder for better compatibility.[/dim]"
+            )
+            console.print()
+
+            if not auto_approve:
+                if not click.confirm(
+                    "Continue with enhancement despite missing /app folder?",
+                    default=True,
+                ):
+                    console.print("✋ [yellow]Enhancement cancelled.[/yellow]")
+                    return
+        else:
+            # Check for common agent files
+            agent_py = app_folder / "agent.py"
+            if agent_py.exists():
+                console.print(
+                    "Detected existing agent structure with [cyan]/app/agent.py[/cyan]"
+                )
+            else:
+                console.print(
+                    "ℹ️  [blue]Found /app folder[/blue] - ensure your agent code is properly organized within it"
+                )
+
+    # Call the create command with in-folder mode enabled
+    ctx.invoke(
+        create,
+        project_name=project_name,
+        agent=agent_spec,
+        deployment_target=deployment_target,
+        cicd_runner=cicd_runner,
+        include_data_ingestion=include_data_ingestion,
+        datastore=datastore,
+        session_type=session_type,
+        debug=debug,
+        output_dir=None,  # Use current directory
+        auto_approve=auto_approve,
+        region=region,
+        skip_checks=skip_checks,
+        in_folder=True,  # Always use in-folder mode for enhance
+        base_template=base_template,
+        skip_welcome=True,  # Skip welcome message since enhance shows its own
+    )