feat: add support for flat structure remote templates (#676)

* feat: add support for flat structure remote templates

Add support for remote templates where agent code is in the root
directory rather than a subdirectory (e.g., adk-python samples).

- Add _detect_flat_structure() to auto-detect flat templates
- Update _infer_agent_directory_for_adk() to handle flat structures
- Add copy_flat_structure_agent_files() for proper file placement
- Allow -dir . flag to explicitly indicate flat structure
- Derive target directory name from template folder name

This enables using templates like:
https://github.com/google/adk-python/tree/main/contributing/samples/bigquery

Author: eliasecchig

agent_starter_pack/cli/utils/remote_template.py

@@ -364,6 +364,40 @@ def fetch_remote_template(
         ) from e
 
 
+def _detect_flat_structure(template_dir: pathlib.Path) -> bool:
+    """Detect if template has a flat structure (agent code in root).
+
+    A flat structure means:
+    - agent.py exists directly in the template root
+    - No obvious agent subdirectory exists (like 'app/' or folder_name as package)
+
+    Args:
+        template_dir: Path to template directory
+
+    Returns:
+        True if template has flat structure, False otherwise
+    """
+    # Check if agent.py exists in root
+    agent_py_in_root = (template_dir / "agent.py").exists()
+    if not agent_py_in_root:
+        return False
+
+    # Check for common agent subdirectory patterns
+    folder_name = template_dir.name.replace("-", "_")
+    potential_agent_dirs = ["app", folder_name]
+
+    for subdir in potential_agent_dirs:
+        subdir_path = template_dir / subdir
+        if subdir_path.is_dir() and (subdir_path / "agent.py").exists():
+            # Found a proper agent subdirectory
+            return False
+
+    logging.debug(
+        f"Detected flat structure in {template_dir}: agent.py in root, no agent subdirectory"
+    )
+    return True
+
+
 def _infer_agent_directory_for_adk(
     template_dir: pathlib.Path, is_adk_sample: bool
 ) -> dict[str, Any]:
@@ -379,19 +413,35 @@ def _infer_agent_directory_for_adk(
     if not is_adk_sample:
         return {}
 
+    # Check for flat structure (agent code in root)
+    is_flat = _detect_flat_structure(template_dir)
+
     # Convert folder name to Python package convention (hyphens to underscores)
     folder_name = template_dir.name
-    agent_directory = folder_name.replace("-", "_")
+    target_agent_directory = folder_name.replace("-", "_")
+
+    if is_flat:
+        logging.debug(
+            f"Flat structure detected: source is '.', target agent_directory is '{target_agent_directory}'"
+        )
+        return {
+            "settings": {
+                "agent_directory": target_agent_directory,
+                "source_agent_directory": ".",  # Special value for flat structure
+            },
+            "has_explicit_config": False,
+            "is_flat_structure": True,
+        }
 
     logging.debug(
-        f"Inferred agent_directory '{agent_directory}' from folder name '{folder_name}' for ADK sample"
+        f"Inferred agent_directory '{target_agent_directory}' from folder name '{folder_name}' for ADK sample"
     )
 
     return {
         "settings": {
-            "agent_directory": agent_directory,
+            "agent_directory": target_agent_directory,
         },
-        "has_explicit_config": False,  # Track that this was inferred
+        "has_explicit_config": False,
     }
 
 
@@ -481,6 +531,19 @@ def load_remote_template_config(
             logging.warning(f"Failed to apply ADK inference for {template_dir}: {e}")
             # Continue with default configuration
 
+    # Detect flat structure for all remote templates (not just ADK samples)
+    # This handles cases where agent.py is in root with no subdirectory
+    if not has_explicit_config and not is_adk_sample:
+        if _detect_flat_structure(template_dir):
+            folder_name = template_dir.name.replace("-", "_")
+            config.setdefault("settings", {})
+            config["settings"]["agent_directory"] = folder_name
+            config["settings"]["source_agent_directory"] = "."
+            config["is_flat_structure"] = True
+            logging.debug(
+                f"Detected flat structure for non-ADK template: source='.', target='{folder_name}'"
+            )
+
     # Add metadata about configuration source
     config["has_explicit_config"] = bool(has_explicit_config)
 

agent_starter_pack/cli/utils/template.py

@@ -230,15 +230,29 @@ def add_base_template_dependencies_interactively(
         return False
 
 
-def validate_agent_directory_name(agent_dir: str) -> None:
+def validate_agent_directory_name(agent_dir: str, allow_dot: bool = False) -> None:
     """Validate that an agent directory name is a valid Python identifier.
 
     Args:
         agent_dir: The agent directory name to validate
+        allow_dot: If True, allows "." as a special value indicating flat structure
 
     Raises:
         ValueError: If the agent directory name is not a valid Python identifier
+
+    Note:
+        The special value "." indicates flat structure - agent code is in the
+        template root. When "." is used, the target directory name will be
+        derived from the template folder name.
     """
+    if agent_dir == ".":
+        if allow_dot:
+            return  # "." is valid when explicitly allowed (will be resolved later)
+        raise ValueError(
+            "Agent directory '.' is not valid in this context. "
+            "Use '.' only to indicate flat structure templates."
+        )
+
     if "-" in agent_dir:
         raise ValueError(
             f"Agent directory '{agent_dir}' contains hyphens (-) which are not allowed. "
@@ -879,7 +893,11 @@ def process_template(
     def get_agent_directory(
         template_config: dict[str, Any], cli_overrides: dict[str, Any] | None = None
     ) -> str:
-        """Get agent directory with CLI override support."""
+        """Get agent directory with CLI override support.
+
+        Handles the special case where agent_directory is "." (flat structure),
+        deriving the target directory name from the remote template folder name.
+        """
         agent_dir = None
         if (
             cli_overrides
@@ -892,6 +910,20 @@ def get_agent_directory(
                 "agent_directory", "app"
             )
 
+        # Handle "." (flat structure) - derive target from folder name
+        if agent_dir == ".":
+            if remote_template_path:
+                # Derive from remote template folder name
+                folder_name = remote_template_path.name.replace("-", "_")
+                logging.debug(
+                    f"Flat structure (-dir .): deriving target '{folder_name}' from folder name"
+                )
+                agent_dir = folder_name
+            else:
+                # Fallback to "app" for non-remote templates
+                logging.debug("Flat structure (-dir .): using 'app' as fallback")
+                agent_dir = "app"
+
         # Validate agent directory is a valid Python identifier
         validate_agent_directory_name(agent_dir)
 
@@ -1239,13 +1271,39 @@ def get_agent_directory(
                             f"Preserved base template {preserve_file} as starter_pack_{base_name}{extension}"
                         )
 
-                copy_files(
-                    remote_template_path,
-                    generated_project_dir,
-                    agent_name=agent_name,
-                    overwrite=True,
-                    agent_directory=agent_directory,
+                # Check if this is a flat structure template
+                # Flat structure can be detected via:
+                # 1. Auto-detection (is_flat_structure flag in remote_config)
+                # 2. source_agent_directory set to "." in config
+                # 3. CLI override with -dir . (agent_directory = ".")
+                cli_agent_dir = (
+                    cli_overrides.get("settings", {}).get("agent_directory")
+                    if cli_overrides
+                    else None
+                )
+                is_flat_structure = (cli_agent_dir == ".") or (
+                    remote_config and remote_config.get("is_flat_structure", False)
                 )
+
+                if is_flat_structure:
+                    # For flat structures, Python files go to agent_directory
+                    logging.debug(
+                        f"Flat structure detected: copying files to {agent_directory}/"
+                    )
+                    copy_flat_structure_agent_files(
+                        remote_template_path,
+                        generated_project_dir,
+                        agent_directory,
+                    )
+                else:
+                    # Standard structure: copy as-is
+                    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")
 
                 # Handle ADK agent compatibility
@@ -1738,3 +1796,54 @@ def copy_deployment_files(
         )
     else:
         logging.warning(f"Deployment target directory not found: {deployment_path}")
+
+
+def copy_flat_structure_agent_files(
+    src: pathlib.Path,
+    dst: pathlib.Path,
+    agent_directory: str,
+) -> None:
+    """Copy agent files from a flat structure template to the agent directory.
+
+    For flat structure templates, Python files (*.py) in the root are copied
+    to the agent directory, while other files are copied to the project root.
+
+    Args:
+        src: Source path (template root with flat structure)
+        dst: Destination path (project root)
+        agent_directory: Target agent directory name
+    """
+    agent_dst = dst / agent_directory
+    agent_dst.mkdir(parents=True, exist_ok=True)
+
+    # Files that should go to agent directory
+    agent_file_extensions = {".py"}
+    # Files to skip entirely
+    skip_files = {"pyproject.toml", "uv.lock", "README.md", ".gitignore"}
+
+    for item in src.iterdir():
+        if item.name.startswith(".") or item.name in skip_files:
+            continue
+        if item.name == "__pycache__":
+            continue
+
+        if item.is_file():
+            if item.suffix in agent_file_extensions:
+                # Python files go to agent directory
+                dest_file = agent_dst / item.name
+                logging.debug(
+                    f"Flat structure: copying {item.name} -> {agent_directory}/{item.name}"
+                )
+                shutil.copy2(item, dest_file)
+            else:
+                # Other files go to project root
+                dest_file = dst / item.name
+                logging.debug(f"Flat structure: copying {item.name} -> {item.name}")
+                shutil.copy2(item, dest_file)
+        elif item.is_dir():
+            # Directories are copied to project root (preserving structure)
+            dest_dir = dst / item.name
+            logging.debug(f"Flat structure: copying directory {item.name}")
+            if dest_dir.exists():
+                shutil.rmtree(dest_dir)
+            shutil.copytree(item, dest_dir)