agent-starter-pack 0.0.11b0__tar.gz → 0.0.12b0__tar.gz

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.12b0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.0.11b0
+Version: 0.0.12b0
 Summary: CLI tool to create GCP-based AI agent projects from templates
 Author-email: Google LLC <agent-starter-pack@google.com>
 License: Apache-2.0
@@ -52,6 +52,7 @@ agent-starter-pack create my-awesome-agent
 ```
 
 **That's it!** You now have a fully functional agent project, complete with a backend, frontend, and deployment infrastructure, ready to explore and customize.
+For more installation options, see the [Installation Guide](docs/installation.md).
 
 ---
 
@@ -113,10 +114,13 @@ This project represents the next evolution of the [e2e-gen-ai-app-starter-pack](
 See the [documentation](docs/) for more details:
 
 - [Why Use the Starter Pack?](docs/why_starter_pack.md)
+- [Installation](docs/installation.md)
 - [Deployment](docs/deployment.md)
 - [Data Ingestion](docs/data-ingestion.md)
 - [Observability](docs/observability.md)
 - [CLI Reference](docs/cli/README.md)
+- [CLI Reference](docs/cli/README.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
 **Video Walkthrough:** A [20-Minute Video Walkthrough](https://youtu.be/kwRG7cnqSu0) is available, showcasing the previous `e2e-gen-ai-app-starter-pack`. A new walkthrough for the `agent-starter-pack` will be released soon!
 

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.12b0}/README.md

@@ -28,6 +28,7 @@ agent-starter-pack create my-awesome-agent
 ```
 
 **That's it!** You now have a fully functional agent project, complete with a backend, frontend, and deployment infrastructure, ready to explore and customize.
+For more installation options, see the [Installation Guide](docs/installation.md).
 
 ---
 
@@ -89,10 +90,13 @@ This project represents the next evolution of the [e2e-gen-ai-app-starter-pack](
 See the [documentation](docs/) for more details:
 
 - [Why Use the Starter Pack?](docs/why_starter_pack.md)
+- [Installation](docs/installation.md)
 - [Deployment](docs/deployment.md)
 - [Data Ingestion](docs/data-ingestion.md)
 - [Observability](docs/observability.md)
 - [CLI Reference](docs/cli/README.md)
+- [CLI Reference](docs/cli/README.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
 **Video Walkthrough:** A [20-Minute Video Walkthrough](https://youtu.be/kwRG7cnqSu0) is available, showcasing the previous `e2e-gen-ai-app-starter-pack`. A new walkthrough for the `agent-starter-pack` will be released soon!
 

agent_starter_pack-0.0.12b0/docs/installation.md

@@ -0,0 +1,72 @@
+# Installation
+
+There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow.
+
+## Using pipx (Recommended)
+
+The recommended way to install the Agent Starter Pack is with [pipx](https://pypa.github.io/pipx/), which installs the package in an isolated environment while making the commands globally available:
+
+```bash
+# Install pipx if you don't have it
+python3 -m pip install --user pipx && python3 -m pipx ensurepath
+source ~/.bashrc  # or ~/.zshrc depending on your shell
+
+# Install the Agent Starter Pack
+pipx install agent-starter-pack
+```
+
+## Using pip with a virtual environment
+
+You can also install the Agent Starter Pack in a virtual environment:
+
+```bash
+# Create and activate a Python virtual environment
+python -m venv venv && source venv/bin/activate
+
+# Install the Agent Starter Pack
+pip install agent-starter-pack
+```
+
+## Using uv (Fast Python package installer)
+
+For a faster installation experience, you can use [uv](https://astral.sh/uv):
+
+```bash
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+source ~/.bashrc  # or ~/.zshrc depending on your shell
+
+# Install the Agent Starter Pack
+uv pip install agent-starter-pack
+```
+
+## Getting Started
+
+After installation, you can create a new agent project:
+
+```bash
+# Create a new agent project
+agent-starter-pack create my-awesome-agent
+```
+
+
+## Upgrading
+
+To upgrade, use the same tool you used for installation:
+
+```bash
+pipx upgrade agent-starter-pack  # Using pipx
+pip install --upgrade agent-starter-pack  # Using pip
+uv pip install --upgrade agent-starter-pack  # Using uv
+```
+
+## Uninstalling
+
+To uninstall, use the same tool you used for installation:
+
+```bash
+pipx uninstall agent-starter-pack # Using pipx
+pip uninstall agent-starter-pack  # Using pip
+uv pip uninstall agent-starter-pack  # Using uv
+```

agent_starter_pack-0.0.12b0/docs/troubleshooting.md

@@ -0,0 +1,104 @@
+# Troubleshooting
+
+This guide helps resolve common issues with the Agent Starter Pack.
+
+## Authentication Issues
+
+For detailed information on authentication with Vertex AI, visit the [official documentation](https://cloud.google.com/vertex-ai/docs/authentication).
+
+### "Could not find credentials" or "Could not find project" Error
+
+**Problem**: Missing credentials error with Vertex AI.
+
+**Solution**:
+
+1.  Log in to Google Cloud: `gcloud auth login --update-adc`
+2.  Set the correct project:
+    ```bash
+    gcloud config set project YOUR_PROJECT_ID
+    gcloud auth application-default set-quota-project YOUR_PROJECT_ID
+    ```
+
+### Vertex AI API Not Enabled
+
+**Problem**: Operations fail because the Vertex AI API is not enabled in your project.
+
+**Solution**:
+
+1. Enable the Vertex AI API:
+   ```bash
+   gcloud services enable aiplatform.googleapis.com
+   ```
+
+2. Verify the API is enabled:
+   ```bash
+   gcloud services list --filter=aiplatform.googleapis.com
+   ```
+
+### Permission Denied Errors
+**Problem**: "Permission denied" errors with Google Cloud APIs.
+
+**Solution**: Ensure your user or service account has the necessary IAM roles.  For example, for Vertex AI, you often need `roles/aiplatform.user`.  Grant roles using the `gcloud projects add-iam-policy-binding` command or the Cloud Console.
+
+### Command Not Found: agent-starter-pack
+
+**Problem**: "Command not found" error after installation.
+
+**Solution**:
+
+1. Verify installation:
+   ```bash
+   pip list | grep agent-starter-pack
+   ```
+2. Check PATH:
+   ```bash
+   echo $PATH
+   ```
+3. Reinstall if needed:
+   ```bash
+   pip install --user agent-starter-pack
+   ```
+4. For pipx:
+   ```bash
+   pipx ensurepath
+   source ~/.bashrc  # or ~/.zshrc
+   ```
+
+## Project Creation Issues
+
+### Project Creation Fails
+
+**Problem**: `agent-starter-pack create` fails.
+
+**Solution**:
+
+1.  **Check Error Messages:** Examine output for clues.
+2.  **Write Permissions:** Ensure write access to the directory.
+3.  **Project Name:** Use lowercase letters, numbers and hyphens only.
+4.  **Debug Mode:** Consider using debug mode to get more detailed error information:
+    ```bash
+    agent-starter-pack create my-project-name --debug
+    ```
+
+### Template Rendering Issues
+
+**Problem**: Project created with placeholders (e.g., `{{ project_id }}`).
+
+**Solution**:
+
+1.  **Delete Project:** Remove the incorrect project directory.
+2.  **Debug Mode:** `agent-starter-pack create my-project --debug`.
+3.  **Check Configuration:** Verify GCP project and authentication setup.
+4. **File an Issue:** If it persists, file a bug report with `--debug` output.
+
+## Getting More Help
+
+If issues persist:
+
+1.  **Check GitHub Issues:** Search for existing Github issues in the `agent-starter-pack` Github repository.
+2.  **File a New Issue:** Provide:
+
+    *   Problem description.
+    *   Steps to reproduce.
+    *   Error messages (preferably run with `--debug` flag for detailed logs).
+    *   Environment: OS, Python version, `agent-starter-pack` version, installation method, shell.

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.12b0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.0.11b"
+version = "0.0.12b"
 description = "CLI tool to create GCP-based AI agent projects from templates"
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },

{agent_starter_pack-0.0.11b0 → agent_starter_pack-0.0.12b0}/src/cli/utils/cicd.py

@@ -257,6 +257,17 @@ def create_github_connection(
             elif status == "PENDING_USER_OAUTH" or status == "PENDING_INSTALL_APP":
                 if attempt < max_retries - 1:  # Don't print waiting on last attempt
                     console.print("⏳ Waiting for GitHub authorization...")
+                    # Extract and print the action URI for user authentication
+                    try:
+                        action_uri = json.loads(result.stdout).get("installationState", {}).get("actionUri")
+                        if action_uri:
+                            console.print("\n🔑 Authentication Required:", style="bold yellow")
+                            console.print(f"Please visit [link={action_uri}]this page[/link] to authenticate Cloud Build with GitHub:")
+                            console.print(f"{action_uri}", style="bold blue")
+                            console.print("(Copy and paste the link into your browser if clicking doesn't work)")
+                            console.print("After completing authentication, return here to continue the setup.\n")
+                    except (json.JSONDecodeError, KeyError) as e:
+                        console.print(f"⚠️ Could not extract authentication link: {e}", style="yellow")
                     time.sleep(10)
                 continue
             else: