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

src/cli/commands/enhance.py

@@ -0,0 +1,302 @@
+# 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 rich.prompt import IntPrompt
+
+from ..utils.logging import display_welcome_banner, handle_cli_error
+from ..utils.template import get_available_agents
+from .create import (
+    create,
+    get_available_base_templates,
+    shared_template_options,
+    validate_base_template,
+)
+
+console = Console()
+
+
+def display_base_template_selection(current_base: str) -> str:
+    """Display available base templates and prompt for selection."""
+    agents = get_available_agents()
+
+    if not agents:
+        raise click.ClickException("No base templates available")
+
+    console.print()
+    console.print("🔧 [bold]Base Template Selection[/bold]")
+    console.print()
+    console.print(f"Your project currently inherits from: [cyan]{current_base}[/cyan]")
+    console.print("Available base templates:")
+
+    # Create a mapping of choices to agent names
+    template_choices = {}
+    choice_num = 1
+    current_choice = None
+
+    for _num, agent in agents.items():
+        template_choices[choice_num] = agent["name"]
+        current_indicator = " (current)" if agent["name"] == current_base else ""
+        console.print(
+            f"  {choice_num}. [bold]{agent['name']}[/]{current_indicator} - [dim]{agent['description']}[/]"
+        )
+        if agent["name"] == current_base:
+            current_choice = choice_num
+        choice_num += 1
+
+    if current_choice is None:
+        current_choice = 1
+
+    console.print()
+    choice = IntPrompt.ask(
+        "Select base template", default=current_choice, show_default=True
+    )
+
+    if choice in template_choices:
+        return template_choices[choice]
+    else:
+        raise ValueError(f"Invalid base template selection: {choice}")
+
+
+@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)
+        original_base_template_name = get_base_template_name(source_config)
+
+        # Interactive base template selection if not provided via CLI and not auto-approved
+        if not base_template and not auto_approve:
+            selected_base_template = display_base_template_selection(
+                original_base_template_name
+            )
+            if selected_base_template != original_base_template_name:
+                # Update CLI overrides with the selected base template
+                cli_overrides["base_template"] = selected_base_template
+                base_template = selected_base_template
+                console.print(
+                    f"✅ Selected base template: [cyan]{selected_base_template}[/cyan]"
+                )
+                console.print()
+
+        # Reload config with potential base template override
+        if cli_overrides.get("base_template"):
+            source_config = load_remote_template_config(current_dir, cli_overrides)
+
+        base_template_name = get_base_template_name(source_config)
+
+        # Show current inheritance info
+        if not auto_approve or base_template:
+            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]"
+            )
+            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
+    )

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: