agent-starter-pack 0.5.0__tar.gz → 0.5.1__tar.gz

{agent_starter_pack-0.5.0 → agent_starter_pack-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.5.0
+Version: 0.5.1
 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

agent_starter_pack-0.5.1/docs/guide/installation.md

@@ -0,0 +1,151 @@
+# Installation
+
+There are several ways to install the Agent Starter Pack. Choose the method that works best for your workflow.
+
+**Want zero setup?** 👉 [Try in Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or in [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs)
+
+## `uvx` for Quick Project Creation
+
+If you have [uv](https://astral.sh/uv) installed, you can create projects without a permanent installation:
+```bash
+uvx agent-starter-pack create my-awesome-agent
+```
+
+## Virtual Environment Installation
+
+Installs into an isolated Python environment.
+
+```bash
+# Create and activate venv
+python -m venv .venv && source .venv/bin/activate # source .venv/Scripts/activate for Windows Git Bash
+
+# Install using pip or uv
+pip install agent-starter-pack
+```
+
+## Persistent CLI Installation
+
+Installs the `agent-starter-pack` command globally.
+
+### With `pipx` (Isolated Global Tool)
+```bash
+# Install pipx (if needed)
+python3 -m pip install --user pipx && python3 -m pipx ensurepath
+
+# Install Agent Starter Pack
+pipx install agent-starter-pack
+```
+
+### With `uv tool install` (Fast, Isolated Global Tool)
+Requires `uv` (see `uvx` section for install).
+```bash
+uv tool install agent-starter-pack
+```
+
+## Create Project (After Persistent/Venv Install)
+
+If you installed via `pipx`, `uv tool install`, or in a virtual environment:
+```bash
+agent-starter-pack create my-awesome-agent
+```
+
+## Managing Installation
+
+### Upgrading
+*   **`uvx`:** Not needed (always uses latest).
+*   **`pipx`:** `pipx upgrade agent-starter-pack`
+*   **`uv tool`:** `uv tool install agent-starter-pack` (this upgrades)
+*   **`pip`/`uv pip` (in .venv):** `(uv) pip install --upgrade agent-starter-pack`
+
+### Uninstalling
+*   **`uvx`:** Not applicable.
+*   **`pipx`:** `pipx uninstall agent-starter-pack`
+*   **`uv tool`:** `uv tool uninstall agent-starter-pack`
+*   **`pip`/`uv pip` (in .venv):** `(uv) pip uninstall agent-starter-pack`
+
+## Troubleshooting Common Installation Issues
+
+### Command Not Found After Installation
+
+If you encounter "command not found" errors after installation:
+
+1.  **Check your PATH**: Ensure that the Python scripts directory is in your PATH:
+    ```bash
+    echo $PATH
+    ```
+2.  **Verify installation location**: Check where the package was installed:
+    ```bash
+    pip show agent-starter-pack
+    ```
+3.  **Manual path addition**: If needed, add the scripts directory to your PATH:
+    ```bash
+    export PATH="$HOME/.local/bin:$PATH"
+    # For user installations
+    ```
+    Add this line to your `~/.bashrc` or `~/.zshrc` for persistence.
+
+### Permission Errors During Installation
+
+If you encounter permission errors:
+
+1.  **Use user installation mode**:
+    ```bash
+    pip install --user agent-starter-pack
+    ```
+2.  **Check directory permissions**:
+    ```bash
+    ls -la ~/.local/bin
+    ```
+3.  **Fix permissions if needed**:
+    ```bash
+    chmod +x ~/.local/bin/agent-starter-pack
+    ```
+
+### Python Version Compatibility Issues
+
+If you encounter Python version errors:
+
+1.  **Check your Python version**:
+    ```bash
+    python --version
+    ```
+2.  **Install a compatible Python version** if needed (3.10 or newer is required).
+3.  **Create a virtual environment with the correct Python version**:
+    ```bash
+    python3.10 -m venv .venv
+    source .venv/bin/activate
+    ```
+
+### Package Dependency Conflicts
+
+If you encounter dependency conflicts:
+
+1.  **Use a clean virtual environment**:
+    ```bash
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install agent-starter-pack
+    ```
+2.  **Update pip and setuptools**:
+    ```bash
+    pip install --upgrade pip setuptools
+    ```
+3.  **Install with verbose output to identify conflicts**:
+    ```bash
+    pip install -v agent-starter-pack
+    ```
+
+### Installation Verification
+
+To verify your installation is working correctly:
+
+1.  **Check the installed version**:
+    ```bash
+    agent-starter-pack --version
+    ```
+2.  **Run the help command**:
+    ```bash
+    agent-starter-pack --help
+    ```
+
+If you continue to experience issues, please [file an issue](https://github.com/GoogleCloudPlatform/agent-starter-pack/issues) with details about your environment and the specific error messages you're encountering.

{agent_starter_pack-0.5.0 → agent_starter_pack-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-starter-pack"
-version = "0.5.0"
+version = "0.5.1"
 description = "CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates."
 authors = [
     { name = "Google LLC", email = "agent-starter-pack@google.com" },

{agent_starter_pack-0.5.0 → agent_starter_pack-0.5.1}/src/frontends/streamlit/frontend/utils/stream_handler.py

@@ -253,10 +253,19 @@ class EventProcessor:
                         msg = f"\n\nTool response: `{content}`"
                         self.stream_handler.new_status(msg)
 
-                    # Handle AI responses
-                    elif content := message.get("content"):
-                        self.final_content += content
-                        self.stream_handler.new_token(content)
+                    # Handle incremental AI response chunks
+                    # These are partial content pieces that need to be accumulated
+                    elif (
+                        message.get("content")
+                        and message.get("type") == "AIMessageChunk"
+                    ):
+                        self.final_content += message.get("content")
+                        self.stream_handler.new_token(message.get("content"))
+
+                    # Handle complete AI responses
+                    # This is used when receiving a full message rather than chunks
+                    elif message.get("content") and message.get("type") == "ai":
+                        self.final_content = message.get("content")
 
         # Handle end of stream
         if self.final_content:

{agent_starter_pack-0.5.0 → agent_starter_pack-0.5.1}/tests/test_frontend/test_utils/test_stream_handler.py

@@ -94,14 +94,20 @@ def test_event_processor_tool_calls() -> None:
         "kwargs": {"tool_call_id": "test_id", "content": "tool response"},
     }
 
+    ai_message_chunk = {
+        "type": "constructor",
+        "kwargs": {"content": "partial ", "type": "AIMessageChunk"},
+    }
+
     final_response_event = {
         "type": "constructor",
-        "kwargs": {"content": "final response"},
+        "kwargs": {"content": "response", "type": "AIMessageChunk"},
     }
 
     client_mock.stream_messages.return_value = [
         (tool_call_event, {}),
         (tool_response_event, {}),
+        (ai_message_chunk, {}),
         (final_response_event, {}),
     ]
 
@@ -116,11 +122,13 @@ def test_event_processor_tool_calls() -> None:
     assert processor.tool_calls[1]["content"] == "tool response"
 
     # Verify final content
-    assert processor.final_content == "final response"
+    assert processor.final_content == "partial response"
 
     # Verify stream handler updates
     assert stream_handler_mock.new_status.call_count == 2
-    assert stream_handler_mock.new_token.call_count == 1
+    assert stream_handler_mock.new_token.call_count == 2
+    stream_handler_mock.new_token.assert_any_call("partial ")
+    stream_handler_mock.new_token.assert_any_call("response")
 
 
 def test_event_processor_direct_response() -> None:
@@ -131,8 +139,20 @@ def test_event_processor_direct_response() -> None:
 
     # Mock stream events with direct response
     response_events: list[tuple[dict[str, Any], dict[str, Any]]] = [
-        ({"type": "constructor", "kwargs": {"content": "Hello"}}, {}),
-        ({"type": "constructor", "kwargs": {"content": " World"}}, {}),
+        (
+            {
+                "type": "constructor",
+                "kwargs": {"content": "Hello", "type": "AIMessageChunk"},
+            },
+            {},
+        ),
+        (
+            {
+                "type": "constructor",
+                "kwargs": {"content": " World", "type": "AIMessageChunk"},
+            },
+            {},
+        ),
     ]
 
     client_mock.stream_messages.return_value = response_events
@@ -159,15 +179,21 @@ def test_event_processor_session_state_updates(mock_uuid: MagicMock) -> None:
 
     # Mock stream events with message that should be added to session state
     client_mock.stream_messages.return_value = [
-        ({"type": "constructor", "kwargs": {"content": "test response"}}, {})
+        (
+            {
+                "type": "constructor",
+                "kwargs": {"content": "test response", "type": "ai"},
+            },
+            {},
+        )
     ]
 
     # Initialize session state with empty messages
     st_mock.session_state.user_chats["test_session"]["messages"] = []
+    st_mock.session_state["user_id"] = "test_user"
+    st_mock.session_state["session_id"] = "test_session"
 
     processor = EventProcessor(st_mock, client_mock, stream_handler_mock)
-    # Set run_id before processing events
-    st_mock.session_state["run_id"] = "test_run"
     processor.process_events()
 
     # Verify stream events call
@@ -215,7 +241,8 @@ def test_event_processor_session_state_updates_with_tools(mock_uuid: MagicMock)
                             "name": "test_tool",
                             "args": {"arg1": "value1"},
                         }
-                    ]
+                    ],
+                    "type": "AIMessageChunk",
                 },
             },
             {},
@@ -223,26 +250,49 @@ def test_event_processor_session_state_updates_with_tools(mock_uuid: MagicMock)
         (
             {
                 "type": "constructor",
-                "kwargs": {"tool_call_id": "test_id", "content": "tool response"},
+                "kwargs": {
+                    "tool_call_id": "test_id",
+                    "content": "tool response",
+                    "type": "tool",
+                },
+            },
+            {},
+        ),
+        (
+            {
+                "type": "constructor",
+                "kwargs": {
+                    "content": "partial response",
+                    "type": "AIMessageChunk",
+                },
+            },
+            {},
+        ),
+        (
+            {
+                "type": "constructor",
+                "kwargs": {
+                    "content": " final",
+                    "type": "AIMessageChunk",
+                },
             },
             {},
         ),
-        ({"type": "constructor", "kwargs": {"content": "final response"}}, {}),
     ]
 
     # Initialize session state with empty messages
     st_mock.session_state.user_chats["test_session"]["messages"] = []
+    st_mock.session_state["user_id"] = "test_user"
+    st_mock.session_state["session_id"] = "test_session"
 
     processor = EventProcessor(st_mock, client_mock, stream_handler_mock)
-    # Set run_id before processing events
-    st_mock.session_state["run_id"] = "test_run"
     processor.process_events()
 
     # Verify session state updates
     messages = st_mock.session_state.user_chats["test_session"]["messages"]
-    assert (
-        len(messages) == 3
-    )  # Should have tool call, tool response, and final response
+
+    # Should have tool call, tool response, and final response
+    assert len(messages) == 3
 
     # Verify tool call message
     assert messages[0]["tool_calls"][0]["name"] == "test_tool"
@@ -251,10 +301,19 @@ def test_event_processor_session_state_updates_with_tools(mock_uuid: MagicMock)
     # Verify tool response message
     assert messages[1]["content"] == "tool response"
     assert messages[1]["tool_call_id"] == "test_id"
+    assert messages[1]["type"] == "tool"
 
     # Verify final response message
-    assert messages[2]["content"] == "final response"
+    assert messages[2]["content"] == "partial response final"
     assert messages[2]["id"] == "test_run"
 
-    # Verify run_id was updated
+    # Verify stream handler was called for tool operations and content chunks
+    stream_handler_mock.new_status.assert_any_call(
+        "\n\nCalling tool: `test_tool` with args: `{'arg1': 'value1'}`"
+    )
+    stream_handler_mock.new_status.assert_any_call("\n\nTool response: `tool response`")
+    stream_handler_mock.new_token.assert_any_call("partial response")
+    stream_handler_mock.new_token.assert_any_call(" final")
+
+    # Verify run_id was set in session state
     assert st_mock.session_state["run_id"] == "test_run"