agent-starter-pack 0.0.1b0__py3-none-any.whl

src/base_template/deployment/terraform/variables.tf

@@ -0,0 +1,202 @@
+# 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.
+
+variable "prod_project_id" {
+  type        = string
+  description = "**Production** Google Cloud Project ID for resource deployment."
+}
+
+variable "staging_project_id" {
+  type        = string
+  description = "**Staging** Google Cloud Project ID for resource deployment."
+}
+
+variable "cicd_runner_project_id" {
+  type        = string
+  description = "Google Cloud Project ID where CI/CD pipelines will execute."
+}
+
+variable "region" {
+  type        = string
+  description = "Google Cloud region for resource deployment."
+  default     = "us-central1"
+}
+
+variable "host_connection_name" {
+  description = "Name of the host connection you created in Cloud Build"
+  type        = string
+}
+
+variable "repository_name" {
+  description = "Name of the repository you'd like to connect to Cloud Build"
+  type        = string
+}
+
+variable "telemetry_bigquery_dataset_id" {
+  type        = string
+  description = "BigQuery dataset ID for telemetry data export."
+  default     = "telemetry_genai_app_sample_sink"
+}
+
+variable "feedback_bigquery_dataset_id" {
+  type        = string
+  description = "BigQuery dataset ID for feedback data export."
+  default     = "feedback_genai_app_sample_sink"
+}
+
+variable "telemetry_logs_filter" {
+  type        = string
+  description = "Log Sink filter for capturing telemetry data. Captures logs with the `traceloop.association.properties.log_type` attribute set to `tracing`."
+  default     = "jsonPayload.attributes.\"traceloop.association.properties.log_type\"=\"tracing\" jsonPayload.resource.attributes.\"service.name\"=\"Sample Chatbot Application\""
+}
+
+variable "feedback_logs_filter" {
+  type        = string
+  description = "Log Sink filter for capturing feedback data. Captures logs where the `log_type` field is `feedback`."
+  default     = "jsonPayload.log_type=\"feedback\""
+}
+
+variable "telemetry_sink_name" {
+  type        = string
+  description = "Name of the telemetry data Log Sink."
+  default     = "telemetry_logs_genai_app_sample"
+}
+
+variable "feedback_sink_name" {
+  type        = string
+  description = "Name of the feedback data Log Sink."
+  default     = "feedback_logs_genai_app_sample"
+}
+
+variable "cicd_runner_sa_name" {
+  description = "Service account name to be used for the CICD processes"
+  type        = string
+  default     = "cicd-runner"
+}
+
+variable "suffix_bucket_name_load_test_results" {
+  description = "Suffix Name of the bucket that will be used to store the results of the load test. Prefix will be project id."
+  type        = string
+  default     = "cicd-load-test-results"
+}
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+variable "cloud_run_app_sa_name" {
+  description = "Service account name to be used for the Cloud Run service"
+  type        = string
+  default     = "{{cookiecutter.project_name}}-cr"
+}
+
+variable "artifact_registry_repo_name" {
+  description = "Name of the Artifact registry repository to be used to push containers"
+  type        = string
+  default     = "genai-containers"
+}
+
+variable "cloud_run_app_roles" {
+  description = "List of roles to assign to the Cloud Run app service account"
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+variable "agentengine_sa_roles" {
+  description = "List of roles to assign to the Agent Engine service account"
+{%- endif %}
+  type        = list(string)
+  default = [
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+    "roles/run.invoker",
+{%- endif %}
+    "roles/aiplatform.user",
+    "roles/discoveryengine.editor",
+    "roles/logging.logWriter",
+    "roles/cloudtrace.agent",
+    "roles/storage.admin"
+  ]
+}
+
+variable "cicd_roles" {
+  description = "List of roles to assign to the CICD runner service account in the CICD project"
+  type        = list(string)
+  default = [
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+    "roles/run.invoker",
+{%- endif %}
+    "roles/storage.admin",
+    "roles/aiplatform.user",
+    "roles/discoveryengine.editor",
+    "roles/logging.logWriter",
+    "roles/cloudtrace.agent",
+    "roles/artifactregistry.writer",
+    "roles/cloudbuild.builds.builder"
+  ]
+}
+
+variable "cicd_sa_deployment_required_roles" {
+  description = "List of roles to assign to the CICD runner service account for the Staging and Prod projects."
+  type        = list(string)
+  default = [
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+    "roles/run.developer",
+{%- endif %}    
+    "roles/iam.serviceAccountUser",
+    "roles/aiplatform.user",
+    "roles/storage.admin"
+  ]
+}
+
+{%- if cookiecutter.data_ingestion %}
+variable "vertexai_pipeline_sa_name" {
+  description = "Service account name to be used for the Vertex AI service"
+  type        = string
+  default     = "data-ingestion-vertexai-sa"
+}
+
+variable "pipeline_cron_schedule" {
+  type        = string
+  description = "Cron expression defining the schedule for automated data ingestion."
+  default     = "0 0 * * 0" # Run at 00:00 UTC every Sunday
+}
+
+variable "data_store_region" {
+  type        = string
+  description = "Google Cloud region for resource deployment."
+  default     = "us"
+}
+
+variable "pipelines_roles" {
+  description = "List of roles to assign to the Vertex AI Pipelines service account"
+  type        = list(string)
+  default = [
+    "roles/storage.admin",
+    "roles/aiplatform.user",
+    "roles/discoveryengine.admin",
+    "roles/logging.logWriter",
+    "roles/artifactregistry.writer",
+    "roles/bigquery.dataEditor",
+    "roles/bigquery.jobUser",
+    "roles/bigquery.readSessionUser",
+    "roles/bigquery.connectionAdmin",
+    "roles/resourcemanager.projectIamAdmin"
+  ]
+}
+
+variable "datastore_name" {
+  description = "The name of the datastore"
+  type = string
+  default = "sample-datastore"
+}
+
+variable "search_engine_name" {
+  description = "The name of the search engine"
+  type = string
+  default = "sample-search-engine"
+}
+{%- endif %}

src/base_template/deployment/terraform/vars/env.tfvars

@@ -0,0 +1,43 @@
+# Your Production Google Cloud project id
+prod_project_id = "your-production-project-id"
+
+# Your Staging / Test Google Cloud project id
+staging_project_id = "your-staging-project-id"
+
+# Your Google Cloud project ID that will be used to host the Cloud Build pipelines.
+cicd_runner_project_id = "your-cicd-project-id"
+
+# Name of the host connection you created in Cloud Build
+host_connection_name = "your-host-connection-name"
+
+# Name of the repository you added to Cloud Build
+repository_name = "your-repository-name"
+
+# The Google Cloud region you will use to deploy the infrastructure
+region = "us-central1"
+
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+cloud_run_app_sa_name = "{{cookiecutter.project_name}}-cr"
+{%- endif %}
+
+telemetry_bigquery_dataset_id = "telemetry_genai_app_sample_sink"
+telemetry_sink_name = "telemetry_logs_genai_app_sample"
+telemetry_logs_filter = "jsonPayload.attributes.\"traceloop.association.properties.log_type\"=\"tracing\" jsonPayload.resource.attributes.\"service.name\"=\"Sample Chatbot Application\""
+
+feedback_bigquery_dataset_id = "feedback_genai_app_sample_sink"
+feedback_sink_name = "feedback_logs_genai_app_sample"
+feedback_logs_filter = "jsonPayload.log_type=\"feedback\""
+
+cicd_runner_sa_name = "cicd-runner"
+
+suffix_bucket_name_load_test_results = "cicd-load-test-results"
+
+{%- if cookiecutter.data_ingestion %}
+search_engine_name = "sample-search-engine"
+datastore_name = "sample-datastore"
+vertexai_pipeline_sa_name = "vertexai-pipelines-sa"
+pipeline_cron_schedule = "0 0 * * 0"
+
+#The value can only be one of "global", "us" and "eu".
+data_store_region = "us"
+{%- endif %}

src/base_template/pyproject.toml

@@ -0,0 +1,113 @@
+[project]
+name = "{{cookiecutter.project_name}}"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Your Name", email = "your@email.com"},
+]
+dependencies = [
+{%- for dep in cookiecutter.extra_dependencies %}
+    "{{ dep }}",
+{%- endfor %}
+    "langchain-core~=0.3.9",
+    "opentelemetry-exporter-gcp-trace~=1.9.0",
+    "traceloop-sdk~=0.38.7",
+    "google-cloud-logging~=3.11.4",
+{%- if cookiecutter.deployment_target == 'cloud_run' %}
+    "google-cloud-aiplatform[evaluation]~=1.80.0",
+    "fastapi~=0.115.8",
+    "uvicorn~=0.34.0"
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+    "google-cloud-aiplatform[evaluation,langchain,reasoningengine]~=1.77.0"
+{%- endif %}
+]
+{% if cookiecutter.deployment_target == 'cloud_run' %}
+requires-python = ">=3.10,<=3.13"
+{% elif cookiecutter.deployment_target == 'agent_engine' %}
+requires-python = ">=3.10,<=3.11"
+{%- endif %}
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.23.8",
+    "nest-asyncio>=1.6.0",
+]
+
+[project.optional-dependencies]
+streamlit = [
+    "streamlit~=1.42.0",
+    "streamlit-extras~=0.4.3",
+    "extra-streamlit-components~=0.1.71",
+    "streamlit-feedback~=0.1.3",
+]
+jupyter = [
+    "jupyter~=1.0.0",
+]
+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",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "W",   # pycodestyle warnings
+    "I",   # isort
+    "C",  # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "UP", # pyupgrade
+    "RUF", # ruff specific rules
+]
+ignore = ["E501", "C901"] # ignore line too long, too complex
+
+[tool.ruff.lint.isort]
+known-first-party = ["app", "frontend"]
+
+[tool.mypy]
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+disallow_subclassing_any = true
+warn_incomplete_stub = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+follow_imports = "silent"
+ignore_missing_imports = true
+explicit_package_bases = true
+disable_error_code = ["misc", "no-untyped-call", "no-any-return"]
+{% if cookiecutter.agent_name == 'multimodal_live_api' %}
+exclude = [".venv","./frontend"]
+{% else %}
+exclude = [".venv"]
+{%- endif %}
+
+[tool.codespell]
+ignore-words-list = "rouge"
+{% if cookiecutter.agent_name == 'multimodal_live_api' %}
+skip = "./locust_env/*,uv.lock,.venv,./frontend"
+{% else %}
+skip = "./locust_env/*,uv.lock,.venv"
+{%- endif %}
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.pytest.ini_options]
+pythonpath = "."
+
+[tool.hatch.build.targets.wheel]
+packages = ["app","frontend"]

src/base_template/tests/unit/test_utils/test_tracing_exporter.py

@@ -0,0 +1,140 @@
+# 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.
+
+from collections.abc import Generator
+from typing import Any
+from unittest.mock import Mock, patch
+
+import pytest
+from google.cloud import logging as google_cloud_logging
+from google.cloud import storage
+from opentelemetry.sdk.trace import ReadableSpan
+
+from app.utils.tracing import CloudTraceLoggingSpanExporter
+
+
+@pytest.fixture
+def mock_logging_client() -> Mock:
+    """Create a mock logging client."""
+    return Mock(spec=google_cloud_logging.Client)
+
+
+@pytest.fixture
+def mock_storage_client() -> Mock:
+    """Create a mock storage client."""
+    return Mock(spec=storage.Client)
+
+
+@pytest.fixture
+def mock_credentials() -> Any:
+    """Create mock credentials."""
+    return Mock()
+
+
+@pytest.fixture
+def patch_auth(mock_credentials: Any) -> Generator[Mock, None, None]:
+    """Patch the google.auth.default function."""
+    with patch(
+        "google.auth.default", return_value=(mock_credentials, "project")
+    ) as mock_auth:
+        yield mock_auth
+
+
+@pytest.fixture
+def patch_clients(
+    mock_logging_client: Mock, mock_storage_client: Mock
+) -> Generator[None, None, None]:
+    """Patch the logging and storage clients."""
+    with patch("google.cloud.logging.Client", return_value=mock_logging_client):
+        with patch("google.cloud.storage.Client", return_value=mock_storage_client):
+            yield
+
+
+@pytest.fixture
+def exporter(
+    mock_logging_client: Mock,
+    mock_storage_client: Mock,
+    patch_auth: Any,
+    mock_credentials: Any,
+    patch_clients: Any,
+) -> CloudTraceLoggingSpanExporter:
+    """Create a CloudTraceLoggingSpanExporter instance for testing."""
+    exporter = CloudTraceLoggingSpanExporter(
+        project_id="test-project",
+        logging_client=mock_logging_client,
+        storage_client=mock_storage_client,
+        bucket_name="test-bucket",
+    )
+    return exporter
+
+
+def test_init(exporter: CloudTraceLoggingSpanExporter) -> None:
+    """Test the initialization of CloudTraceLoggingSpanExporter."""
+    assert exporter.project_id == "test-project"
+    assert exporter.bucket_name == "test-bucket"
+    assert exporter.debug is False
+
+
+def test_store_in_gcs(exporter: CloudTraceLoggingSpanExporter) -> None:
+    """Test the store_in_gcs method of CloudTraceLoggingSpanExporter."""
+    span_id = "test-span-id"
+    content = "test-content"
+    uri = exporter.store_in_gcs(content, span_id)
+    assert uri == f"gs://test-bucket/spans/{span_id}.json"
+    exporter.bucket.blob.assert_called_once_with(f"spans/{span_id}.json")
+
+
+@patch("json.dumps")
+def test_process_large_attributes_small_payload(
+    mock_json_dumps: Mock, exporter: CloudTraceLoggingSpanExporter
+) -> None:
+    """Test processing of small payload attributes."""
+    mock_json_dumps.return_value = "a" * 100  # Small payload
+    span_dict = {"attributes": {"key": "value"}}
+    result = exporter._process_large_attributes(span_dict, "span-id")
+    assert result == span_dict
+
+
+@patch("json.dumps")
+def test_process_large_attributes_large_payload(
+    mock_json_dumps: Mock, exporter: CloudTraceLoggingSpanExporter
+) -> None:
+    """Test processing of large payload attributes."""
+    mock_json_dumps.return_value = "a" * (400 * 1024 + 1)  # Large payload
+    span_dict = {
+        "attributes": {
+            "key1": "value1",
+        }
+    }
+    result = exporter._process_large_attributes(span_dict, "span-id")
+    assert "uri_payload" in result["attributes"]
+    assert "url_payload" in result["attributes"]
+
+
+@patch.object(CloudTraceLoggingSpanExporter, "_process_large_attributes")
+def test_export(
+    mock_process_large_attributes: Mock, exporter: CloudTraceLoggingSpanExporter
+) -> None:
+    """Test the export method of CloudTraceLoggingSpanExporter."""
+    mock_span = Mock(spec=ReadableSpan)
+    mock_span.get_span_context.return_value.trace_id = 123
+    mock_span.get_span_context.return_value.span_id = 456
+    mock_span.to_json.return_value = '{"key": "value"}'
+
+    mock_process_large_attributes.return_value = {"processed": "data"}
+
+    exporter.export([mock_span])
+
+    mock_process_large_attributes.assert_called_once()
+    exporter.logger.log_struct.assert_called_once()