feat: add support for flat structure remote templates

[eliasecchig]

Summary

• Add auto-detection for flat structure templates (agent.py in root)
• Support -dir . flag to explicitly indicate flat structure
• Derive target directory name from template folder name
• Add comprehensive tests for the new functionality

Problem

Remote templates like adk-python samples have a "flat" structure where agent code is directly in the template root, not in a subdirectory:

bigquery/
├── agent.py      <- code is here
├── __init__.py
└── README.md

But agent-starter-pack expected a nested structure:

bigquery/
├── app/          <- expected code here
│   ├── agent.py
│   └── __init__.py
└── pyproject.toml

Solution

• _detect_flat_structure(): Auto-detects when agent.py is in root with no agent subdirectory
• copy_flat_structure_agent_files(): Copies Python files to agent directory, other files to project root
• -dir . flag: Explicitly indicate flat structure when auto-detection might not trigger
• Target directory derived from folder name (e.g., bigquery → bigquery/)

Usage

Auto-detection (works automatically):

uvx agent-starter-pack create -a "https://github.com/google/adk-python/tree/main/contributing/samples/bigquery" -p -s -y -d agent_engine --output-dir target myproject

Explicit flag:

uvx agent-starter-pack create -a "..." -dir . -p -s -y -d agent_engine --output-dir target myproject

[gemini-code-assist]

Summary of Changes

Hello @eliasecchig, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the agent-starter-pack's ability to handle diverse remote template structures. Previously, the tool expected agent code to reside in a nested subdirectory. This change introduces robust support for "flat" templates, where the agent.py file is directly in the template's root. This is achieved through automatic detection of such structures, an explicit CLI flag (-dir .) for user control, and a refined file copying process that intelligently places Python agent files into a newly created, appropriately named subdirectory within the generated project, while preserving other template files in the project root. This ensures broader compatibility with various remote template formats, such as ADK-Python samples.

Highlights

• Automatic Flat Structure Detection: The system now automatically identifies remote templates where agent.py is in the root directory, rather than a nested subdirectory.
• Explicit Flat Structure Flag: Users can explicitly indicate a flat structure using the new -dir . command-line flag, overriding auto-detection if needed.
• Dynamic Agent Directory Naming: For flat structures, the target agent directory is now intelligently derived from the template's folder name (e.g., bigquery template results in a bigquery/ agent directory).
• Specialized File Copying Logic: A new utility function copy_flat_structure_agent_files ensures that Python files from flat templates are correctly moved into the designated agent subdirectory, while other non-Python files and subdirectories are placed in the project root.
• Comprehensive Test Coverage: New unit and integration tests have been added to validate the flat structure detection, explicit flag handling, and file copying mechanisms.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds support for flat-structured remote templates, where agent code resides in the root directory rather than a subdirectory. This is a valuable feature that increases flexibility. The implementation includes auto-detection of the flat structure, an explicit -dir . flag for manual override, and logic to correctly place files in the new project structure. The changes are well-tested with both new unit tests and integration tests, which is excellent. I have a couple of minor suggestions to improve code clarity and remove some redundancy, but overall, this is a solid contribution.