agent-starter-pack 0.9.0__tar.gz → 0.9.2__tar.gz

agent_starter_pack-0.9.2/.cloudbuild/ci/test_makefile.yaml

@@ -0,0 +1,36 @@
+# 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.
+
+steps:
+  # Sync dependencies
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv sync --locked
+
+  # Run unit tests using pytest
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: test-templated-agents
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/integration/test_makefile_usability.py
+
+logsBucket: gs://${PROJECT_ID}-logs-data/build-logs
+options:
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/.cloudbuild/terraform/build_triggers.tf

@@ -46,6 +46,16 @@ locals {
     ".cloudbuild/**",
   ]
 
+  makefile_usability_included_files = [
+    "src/cli/**",
+    "src/base_template/**",
+    "src/deployment_targets/**",
+    "tests/integration/test_makefile_usability.py",
+    "pyproject.toml",
+    "uv.lock",
+    ".cloudbuild/**",
+  ]
+
   # Define a local variable for agent/deployment combinations
   agent_testing_combinations = [
     {
@@ -341,3 +351,25 @@ resource "google_cloudbuild_trigger" "pr_test_remote_template" {
   ignored_files      = local.common_ignored_files
   include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
 }
+
+# g. Create Makefile usability Test trigger for PR requests
+resource "google_cloudbuild_trigger" "pr_test_makefile" {
+  name            = "pr-test-makefile"
+  project         = var.cicd_runner_project_id
+  location        = var.region
+  description     = "Trigger for PR checks on Makefile usability"
+  service_account = resource.google_service_account.cicd_runner_sa.id
+
+  repository_event_config {
+    repository = local.repository_path
+    pull_request {
+      branch          = "main"
+      comment_control = "COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY"
+    }
+  }
+
+  filename           = ".cloudbuild/ci/test_makefile.yaml"
+  included_files     = local.makefile_usability_included_files
+  ignored_files      = local.common_ignored_files
+  include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
+}

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.9.0
+Version: 0.9.2
 Summary: CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates.
 Author-email: Google LLC <agent-starter-pack@google.com>
 License: Apache-2.0
@@ -16,11 +16,9 @@ Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.29.5; extra == 'jupyter'
 Requires-Dist: jupyter; extra == 'jupyter'
 Provides-Extra: lint
-Requires-Dist: codespell~=2.2.0; extra == 'lint'
-Requires-Dist: mypy~=1.15.0; extra == 'lint'
-Requires-Dist: ruff>=0.4.6; extra == 'lint'
-Requires-Dist: types-pyyaml~=6.0.12.20240917; extra == 'lint'
-Requires-Dist: types-requests~=2.32.0.20240914; extra == 'lint'
+Requires-Dist: codespell; extra == 'lint'
+Requires-Dist: mypy; extra == 'lint'
+Requires-Dist: ruff; extra == 'lint'
 Description-Content-Type: text/markdown
 
 # 🚀 Agent Starter Pack

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/docs/guide/remote-templating.md

@@ -1,8 +1,6 @@
 # Remote Templates
 
-With remote templating, you can create and share your own agent starter packs without needing to fork the main repository. A remote template is a Git repository that the `agent-starter-pack` CLI can use as a blueprint to create new agent projects. This allows for easy sharing and reuse of customized agent setups.
-
-This guide covers how to build, test, and use remote templates.
+A remote template is a Git repository that the agent-starter-pack CLI uses to generate new **agent codebases**—the local directories containing your agent's code, configuration, and dependencies. It empowers you to create and share your **own production-ready starter packs** by packaging your **custom agent logic, dependencies, and configurations**. This guide covers how to build, test, and use them.
 
 ## Quickstart: Creating Your First Remote Template
 
@@ -10,7 +8,7 @@ Let's build a simple remote template that customizes the built-in `adk_base` age
 
 ### Step 1: Create the Template Directory Structure
 
-A remote template is structured just like a standard agent project. The only special part is the `.template/` directory, which holds the configuration.
+A remote template is structured just like a standard **agent codebase**. The only special part is the `.template/` directory, which holds the configuration.
 
 Create the following structure on your local machine:
 
@@ -87,7 +85,7 @@ Run the `create` command from the directory *outside* of your template folder:
 uvx agent-starter-pack create my-test-agent -a local@./my-first-remote-template
 ```
 
-This creates a new project `my-test-agent` using your local template.
+This creates a new **agent** named `my-test-agent` using your local template.
 
 ### Step 5: Publish and Use Your Template
 
@@ -105,7 +103,7 @@ uvx agent-starter-pack create my-remote-agent -a $REPO_URL
 A remote template repository mirrors the structure of a standard agent. The templating engine copies the entire contents of your repository and overlays them onto the base agent.
 
 -   **Your Agent Files (`app/`, `tests/`, etc.)**: These should be at the root of your repository. They will overwrite the corresponding files from the `base_template`.
--   **`.template/` directory**: This special directory is **only** for the `templateconfig.yaml` file. It is read by the CLI for configuration but is not copied into the final project.
+-   **`.template/` directory**: This special directory is **only** for the `templateconfig.yaml` file. It is read by the CLI for configuration but is not copied into the final generated **agent**.
 -   **Dependencies (`pyproject.toml`, `uv.lock`)**: These must be at the root of your repository.
 
 **Example Structure:**
@@ -124,7 +122,7 @@ my-awesome-template/
 
 Files are copied and overlaid in the following order, with later steps overwriting earlier ones if files have the same name and path:
 
-1.  **[Base Project Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/base_template)**: The foundational files from the starter pack.
+1.  **[Base Template Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/base_template)**: The foundational files from the starter pack.
 2.  **[Deployment Target Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/deployment_targets)**: Files for the chosen deployment target (e.g., `cloud_run`).
 3.  **[Frontend Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/src/frontends)** (Optional): If a `frontend_type` is specified, its files are copied.
 4.  **[Base Agent Files](https://github.com/GoogleCloudPlatform/agent-starter-pack/tree/main/agents)**: The application logic from the `base_template` you specified (e.g., files from `agents/adk_base/`).
@@ -137,27 +135,20 @@ You have full control over the Python dependencies. Both `pyproject.toml` and `u
 
 *   **`uv.lock`**: Strongly recommended to ensure reproducibility.
     *   If present, guarantees exact dependency versions.
-    *   If missing, falls back to base template's lock file. A new lock file will be generatede by the user when performing installation.
+    *   If missing, falls back to base template's lock file. A new lock file will be generated by the user when performing installation.
 
 **Best Practice:** Always run `uv lock` after changing dependencies and commit the resulting lock file.
 
 ## Makefile Behavior
 
-You cannot replace the `Makefile` from the `base_template`. However, you can add new commands or override existing ones via the `settings.commands` section in your `templateconfig.yaml`.
+If your remote template includes a `Makefile` at the root, it will be used as the primary `Makefile` for the generated project. The system intelligently merges it with the `base_template`'s `Makefile` to ensure that essential commands from the starter pack are not lost.
 
-**Example:**
-```yaml
-settings:
-  commands:
-    override:
-      # Replaces the default 'make install' command
-      install: "uv sync --dev --extra jupyter"
-    extra:
-      # Adds 'make custom-lint'
-      custom-lint:
-        command: "ruff check ."
-        description: "Run a custom lint check."
-```
+Here's how the merge logic works:
+- **Your Commands Take Precedence**: If a command exists in both your remote `Makefile` and the base `Makefile`, your version is kept.
+- **New Commands are Added**: Any commands from your `Makefile` are added.
+- **Base Commands are Appended**: Any commands that are in the base `Makefile` but not in yours are appended to your `Makefile`, under a clear separator comment.
+
+This allows you to completely customize the `Makefile` while still inheriting the standard functionality of the starter pack.
 
 ## Configuration Reference
 
@@ -165,7 +156,7 @@ The `templateconfig.yaml` file is the control center for defining an agent's pro
 
 ## Usage Reference
 
-### Creating a Project from a Template
+### Creating an Agent from a Template
 
 Use the `create` command with the `--agent` (`-a`) flag.
 
@@ -180,15 +171,15 @@ Use the `create` command with the `--agent` (`-a`) flag.
     uvx agent-starter-pack create my-agent -a github.com/my-org/my-repo/path-to-template@develop
     ```
 
-*   **ADK Samples Shortcut:** A convenient alias for official Google agent examples. It allows you to create projects from the [google/adk-samples](https://github.com/google/adk-samples) repository without needing to type the full URL.
+*   **ADK Samples Shortcut:** A convenient alias for official Google agent examples. It allows you to create **agents** from the [google/adk-samples](https://github.com/google/adk-samples) repository without needing to type the full URL.
     ```bash
-    # Creates a project from the 'gemini-fullstack' template in adk-samples
+    # Creates an agent from the 'gemini-fullstack' template in adk-samples
     uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
     ```
 
 *   **Local Testing:**
     ```bash
-    uvx agent-starter-pack create my-test-project -a local@./path/to/your/template
+    uvx agent-starter-pack create my-test-agent -a local@./path/to/your/template
     ```
 
 ### Listing Available Agents
@@ -208,4 +199,4 @@ The `list` command helps you discover templates.
 *   **List Official ADK Samples:**
     ```bash
     uvx agent-starter-pack list --adk
-    ```
+    ```

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/docs/guide/template-config-reference.md

@@ -23,50 +23,5 @@ This object contains fields that control the generated project's features and be
 | `frontend_type`             | string         | Specifies the frontend to use. Examples: `streamlit`, `live_api_react`. Defaults to `streamlit`.                                             |
 | `requires_data_ingestion`   | boolean        | If `true`, the user will be prompted to configure a datastore.                                                                              |
 | `requires_session`          | boolean        | If `true`, the user will be prompted to choose a session storage type (e.g., `alloydb`) when using the `cloud_run` target.                    |
+| `interactive_command`       | string         | The `make` command to run for starting the agent, after the agent code is being created (e.g., `make playground`, `make dev`). Defaults to `playground`. |
 | `extra_dependencies`        | list(string)   | **Note:** This field is ignored by remote templates. It is used internally by the starter pack's built-in templates. Your `pyproject.toml` is the single source of truth for dependencies. |
-| `commands`                  | object         | Allows for customizing the `Makefile` in the generated project. See `commands` section below.                                               |
-
-## The `commands` Object
-
-This object allows you to add new `make` commands or override existing ones.
-
-### `override`
-Use this to change the behavior of a default command.
-
-```yaml
-settings:
-  commands:
-    override:
-      # Replaces the default 'make install' command
-      install: "uv sync --dev --extra jupyter && npm --prefix frontend install"
-```
-
-### `extra`
-Use this to add new commands to the `Makefile`.
-
--   **Simple Command**:
-    ```yaml
-    settings:
-      commands:
-        extra:
-          # Adds 'make custom-lint'
-          custom-lint:
-            command: "ruff check ."
-            description: "Run a custom lint check."
-    ```
-
--   **Deployment-Specific Command**:
-    You can provide different versions of a command based on the chosen `deployment_target`.
-
-    ```yaml
-    settings:
-      commands:
-        extra:
-          dev-backend:
-            command:
-              # Command for 'make dev-backend' if target is 'agent_engine'
-              agent_engine: 'uv run adk api_server app --allow_origins="*"'
-              # Command for 'make dev-backend' if target is 'cloud_run'
-              cloud_run: 'ALLOW_ORIGINS="*" uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 --reload'
-            description: "Start the backend development server."
-    ```

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.9.0"
+version = "0.9.2"
 description = "CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates."
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },
@@ -43,6 +43,8 @@ dev = [
     "sphinx-rtd-theme~=2.0.0",
     "streamlit~=1.42.0",
     "streamlit-feedback~=0.1.4",
+    "types-PyYAML",
+    "types-requests",
     "watchdog~=6.0.0",
 ]
 
@@ -53,11 +55,9 @@ jupyter = [
 ]
 
 lint = [
-    "ruff>=0.4.6",
-    "mypy~=1.15.0",
-    "codespell~=2.2.0",
-    "types-pyyaml~=6.0.12.20240917",
-    "types-requests~=2.32.0.20240914",
+    "ruff",
+    "mypy",
+    "codespell",
 ]
 
 [tool.pytest.ini_options]

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/src/cli/commands/create.py

@@ -15,14 +15,16 @@
 import logging
 import os
 import pathlib
+import shutil
 import subprocess
+import tempfile
 
 import click
 from click.core import ParameterSource
 from rich.console import Console
 from rich.prompt import IntPrompt, Prompt
 
-from ..utils.datastores import DATASTORE_TYPES
+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.remote_template import (
@@ -34,6 +36,7 @@ from ..utils.remote_template import (
 )
 from ..utils.template import (
     get_available_agents,
+    get_deployment_targets,
     get_template_path,
     load_template_config,
     process_template,
@@ -128,7 +131,7 @@ def normalize_project_name(project_name: str) -> str:
 @click.option(
     "--skip-checks",
     is_flag=True,
-    help="Skip verification checks for uv, GCP and Vertex AI",
+    help="Skip verification checks for GCP and Vertex AI",
     default=False,
 )
 @handle_cli_error
@@ -155,7 +158,7 @@ def create(
                 style="bold blue",
             )
             console.print(
-                "Powered by ([link=https://goo.gle/agent-starter-pack]Google's Agent Starter Pack [/link])\n",
+                "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"
@@ -201,17 +204,28 @@ def create(
         # Agent selection - handle remote templates
         selected_agent = None
         template_source_path = None
+        temp_dir_to_clean = None
 
         if agent:
             if agent.startswith("local@"):
                 path_str = agent.split("@", 1)[1]
-                template_source_path = pathlib.Path(path_str).resolve()
-                if not template_source_path.is_dir():
+                local_path = pathlib.Path(path_str).resolve()
+                if not local_path.is_dir():
                     raise click.ClickException(
-                        f"Local path not found or not a directory: {template_source_path}"
+                        f"Local path not found or not a directory: {local_path}"
                     )
+
+                # Create a temporary directory and copy the local template to it
+                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)
+
                 selected_agent = f"local_{template_source_path.name}"
-                console.print(f"Using local template: {template_source_path}")
+                console.print(f"Using local template: {local_path}")
+                logging.debug(
+                    f"Copied local template to temporary dir: {template_source_path}"
+                )
             else:
                 # Check if it's a remote template specification
                 remote_spec = parse_agent_spec(agent)
@@ -223,7 +237,10 @@ def create(
                         )
                     else:
                         console.print(f"Fetching remote template: {agent}")
-                    template_source_path = fetch_remote_template(remote_spec)
+                    template_source_path, temp_dir_path = fetch_remote_template(
+                        remote_spec
+                    )
+                    temp_dir_to_clean = str(temp_dir_path)
                     selected_agent = f"remote_{hash(agent)}"  # Generate unique name for remote template
                 else:
                     # Handle local agent selection
@@ -244,13 +261,17 @@ def create(
                                 f"Invalid agent name or number: {agent}"
                             ) from err
 
-        final_agent = (
-            selected_agent
-            if selected_agent
-            else display_agent_selection(deployment_target)
-        )
+        # Agent selection
+        final_agent = selected_agent
+        if not final_agent:
+            if auto_approve:
+                raise click.ClickException(
+                    "Error: --agent is required when running with --auto-approve."
+                )
+            final_agent = display_agent_selection(deployment_target)
+
         if debug:
-            logging.debug(f"Selected agent: {agent}")
+            logging.debug(f"Selected agent: {final_agent}")
 
         # Load template configuration based on whether it's remote or local
         if template_source_path:
@@ -302,14 +323,19 @@ def create(
             config = load_template_config(template_path)
         # Data ingestion and datastore selection
         if include_data_ingestion or datastore:
-            # If datastore is specified but include_data_ingestion is not, set it to True
             include_data_ingestion = True
-
-            # If include_data_ingestion is True but no datastore is specified, prompt for it
             if not datastore:
-                # Pass a flag to indicate this is from explicit CLI flag
-                datastore = prompt_datastore_selection(final_agent, from_cli_flag=True)
-
+                if auto_approve:
+                    # Default to the first available datastore in non-interactive mode
+                    datastore = next(iter(DATASTORES.keys()))
+                    console.print(
+                        f"Info: --datastore not specified. Defaulting to '{datastore}' in auto-approve mode.",
+                        style="yellow",
+                    )
+                else:
+                    datastore = prompt_datastore_selection(
+                        final_agent, from_cli_flag=True
+                    )
             if debug:
                 logging.debug(f"Data ingestion enabled: {include_data_ingestion}")
                 logging.debug(f"Selected datastore type: {datastore}")
@@ -317,8 +343,15 @@ def create(
             # Check if the agent requires data ingestion
             if config and config.get("settings", {}).get("requires_data_ingestion"):
                 include_data_ingestion = True
-                datastore = prompt_datastore_selection(final_agent)
-
+                if not datastore:
+                    if auto_approve:
+                        datastore = next(iter(DATASTORES.keys()))
+                        console.print(
+                            f"Info: --datastore not specified. Defaulting to '{datastore}' in auto-approve mode.",
+                            style="yellow",
+                        )
+                    else:
+                        datastore = prompt_datastore_selection(final_agent)
                 if debug:
                     logging.debug(
                         f"Data ingestion required by agent: {include_data_ingestion}"
@@ -334,13 +367,25 @@ def create(
             deployment_agent_name = get_base_template_name(config)
             remote_config = config
 
-        final_deployment = (
-            deployment_target
-            if deployment_target
-            else prompt_deployment_target(
+        final_deployment = deployment_target
+        if not final_deployment:
+            available_targets = get_deployment_targets(
                 deployment_agent_name, remote_config=remote_config
             )
-        )
+            if auto_approve:
+                if not available_targets:
+                    raise click.ClickException(
+                        f"Error: No deployment targets available for agent '{deployment_agent_name}'."
+                    )
+                final_deployment = available_targets[0]
+                console.print(
+                    f"Info: --deployment-target not specified. Defaulting to '{final_deployment}' in auto-approve mode.",
+                    style="yellow",
+                )
+            else:
+                final_deployment = prompt_deployment_target(
+                    deployment_agent_name, remote_config=remote_config
+                )
         if debug:
             logging.debug(f"Selected deployment target: {final_deployment}")
 
@@ -359,8 +404,19 @@ def create(
                 )
                 return
 
-            if final_deployment in ("cloud_run") and not session_type:
-                final_session_type = prompt_session_type_selection()
+            if (
+                final_deployment is not None
+                and final_deployment in ("cloud_run")
+                and not session_type
+            ):
+                if auto_approve:
+                    final_session_type = "in_memory"
+                    console.print(
+                        "Info: --session-type not specified. Defaulting to 'in_memory' in auto-approve mode.",
+                        style="yellow",
+                    )
+                else:
+                    final_session_type = prompt_session_type_selection()
         else:
             # Agents that don't require session management always use in-memory sessions
             final_session_type = "in_memory"
@@ -441,10 +497,22 @@ def create(
                 remote_template_path=template_source_path,
                 remote_config=config if template_source_path else None,
             )
-        finally:
+
             # Replace region in all files if a different region was specified
             if region != "us-central1":
                 replace_region_in_files(project_path, region, debug=debug)
+        finally:
+            # Clean up the temporary directory if one was created
+            if temp_dir_to_clean:
+                try:
+                    shutil.rmtree(temp_dir_to_clean)
+                    logging.debug(
+                        f"Successfully cleaned up temporary directory: {temp_dir_to_clean}"
+                    )
+                except OSError as e:
+                    logging.warning(
+                        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
@@ -474,14 +542,12 @@ def create(
         console.print("\n🚀 To get started, run the following command:")
 
         # Check if the agent has a 'dev' command in its settings
-        if config["settings"].get("commands", {}).get("extra", {}).get("dev"):
-            console.print(
-                f"   [bold bright_green]cd {cd_path} && make install && make dev[/]"
-            )
-        else:
-            console.print(
-                f"   [bold bright_green]cd {cd_path} && make install && make playground[/]"
-            )
+        interactive_command = config.get("settings", {}).get(
+            "interactive_command", "playground"
+        )
+        console.print(
+            f"   [bold bright_green]cd {cd_path} && make install && make {interactive_command}[/]"
+        )
     except Exception:
         if debug:
             logging.exception(

{agent_starter_pack-0.9.0 → agent_starter_pack-0.9.2}/src/cli/commands/list.py

@@ -82,15 +82,9 @@ def list_remote_agents(remote_source: str, scan_from_root: bool = False) -> None
         # specific template directory within the repo.
         template_dir_path = fetch_remote_template(spec)
 
-        if scan_from_root:
-            # For ADK, we want to scan the entire repo. We need to find the
-            # root of the repo and scan from there.
-            scan_path = template_dir_path
-            while not (scan_path / ".git").exists() and scan_path.parent != scan_path:
-                scan_path = scan_path.parent
-        else:
-            # For other git repos, respect the path given in the URL.
-            scan_path = template_dir_path
+        # fetch_remote_template always returns a tuple of (repo_path, template_path)
+        repo_path, template_path = template_dir_path
+        scan_path = repo_path if scan_from_root else template_path
 
         display_agents_from_path(scan_path, remote_source)