solace-agent-mesh 1.7.1__py3-none-any.whl → 1.13.2__py3-none-any.whl

solace_agent_mesh/agent/adk/alembic/README

@@ -0,0 +1,74 @@
+# ADK Database Schema Migrations
+
+This directory contains Alembic migrations for Google ADK database schema compatibility.
+
+## Overview
+
+Migrations are automatically executed on agent startup when using SQL session services. This ensures your database schema stays compatible with the installed version of Google ADK.
+
+## How It Works
+
+1. **Automatic Migration**: When an agent starts with `session_service.type: sql`, the migration system automatically runs
+2. **Schema Detection**: Alembic compares ADK's model definitions against your actual database schema
+3. **Safe Updates**: Only missing columns/tables are added - existing data is never modified or deleted
+4. **Version Tracking**: Migration history is tracked in the `alembic_version` table in your database
+
+## Migration Files
+
+Migrations are stored in the `versions/` subdirectory:
+- Each file represents a specific schema change
+- Files are named with revision ID + description
+- Migrations run in chronological order
+
+## Creating New Migrations
+
+When Google releases a new ADK version with schema changes:
+
+```bash
+# Navigate to this directory
+cd src/solace_agent_mesh/agent/adk
+
+# Generate migration (auto-detects schema differences)
+alembic revision --autogenerate -m "Update for ADK x.x.x"
+
+# Review the generated migration in versions/
+# Then commit it to version control
+```
+
+## Official ADK Resources
+
+**Example Migration:**
+- https://github.com/google/adk-python/tree/main/contributing/samples/migrate_session_db
+
+**Migration Script:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/google/adk-python/main/scripts/db_migration.sh
+```
+
+**Documentation:**
+- ADK Repository: https://github.com/google/adk-python
+- ADK Releases: https://github.com/google/adk-python/releases
+
+## Troubleshooting
+
+### Manual Migration
+
+To run migrations manually:
+```bash
+cd src/solace_agent_mesh/agent/adk
+alembic upgrade head
+```
+
+### View Migration Status
+
+```bash
+cd src/solace_agent_mesh/agent/adk
+alembic current
+alembic history
+```
+
+## Schema Source
+
+All schema definitions come from:
+- Module: `google.adk.sessions.database_session_service`
+- Models: `StorageSession`, `StorageEvent`, `StorageAppState`, `StorageUserState`

solace_agent_mesh/agent/adk/alembic/env.py

@@ -0,0 +1,77 @@
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+from google.adk.sessions.database_session_service import Base
+# target_metadata = mymodel.Base.metadata
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode, using existing connection.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    # Check if we have an engine passed from the calling code
+    connectable = config.attributes.get('connection', None)
+    if connectable is None:
+        # Fallback: create engine from config (for CLI usage)
+        from sqlalchemy import engine_from_config
+        connectable = engine_from_config(
+            config.get_section(config.config_ini_section, {}),
+            prefix="sqlalchemy.",
+            poolclass=pool.NullPool,
+        )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

solace_agent_mesh/agent/adk/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

solace_agent_mesh/agent/adk/alembic/versions/e2902798564d_adk_session_db_upgrade.py

@@ -0,0 +1,52 @@
+import google.adk.sessions.database_session_service
+"""ADK session DB upgrade
+
+Revision ID: e2902798564d
+Revises: 
+Create Date: 2025-11-12 10:59:41.286752
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'e2902798564d'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def column_exists(table_name: str, column_name: str) -> bool:
+    """Check if a column exists in a table."""
+    bind = op.get_bind()
+    inspector = inspect(bind)
+    columns = [col['name'] for col in inspector.get_columns(table_name)]
+    return column_name in columns
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    if not column_exists('events', 'custom_metadata'):
+        op.add_column('events', sa.Column('custom_metadata', google.adk.sessions.database_session_service.DynamicJSON(), nullable=True))
+
+    if not column_exists('events', 'usage_metadata'):
+        op.add_column('events', sa.Column('usage_metadata', google.adk.sessions.database_session_service.DynamicJSON(), nullable=True))
+
+    if not column_exists('events', 'citation_metadata'):
+        op.add_column('events', sa.Column('citation_metadata', google.adk.sessions.database_session_service.DynamicJSON(), nullable=True))
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    if column_exists('events', 'citation_metadata'):
+        op.drop_column('events', 'citation_metadata')
+
+    if column_exists('events', 'usage_metadata'):
+        op.drop_column('events', 'usage_metadata')
+
+    if column_exists('events', 'custom_metadata'):
+        op.drop_column('events', 'custom_metadata')

solace_agent_mesh/agent/adk/alembic.ini

@@ -0,0 +1,112 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+# Note: This will be set programmatically at runtime
+sqlalchemy.url =
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME

solace_agent_mesh/agent/adk/artifacts/filesystem_artifact_service.py

@@ -10,6 +10,7 @@ import shutil
 import unicodedata
 
 from google.adk.artifacts import BaseArtifactService
+from google.adk.artifacts.base_artifact_service import ArtifactVersion
 from google.genai import types as adk_types
 from typing_extensions import override
 
@@ -372,6 +373,169 @@ class FilesystemArtifactService(BaseArtifactService):
         logger.debug("%sFound versions: %s", log_prefix, sorted_versions)
         return sorted_versions
 
+    @override
+    async def list_artifact_versions(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        filename: str,
+        session_id: str,
+    ) -> list[ArtifactVersion]:
+        """Lists all versions and their metadata for a specific artifact."""
+        log_prefix = f"[FSArtifact:ListArtifactVersions:{filename}] "
+        filename = self._normalize_filename_unicode(filename)
+        artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
+        artifact_versions = []
+
+        if not await asyncio.to_thread(os.path.isdir, artifact_dir):
+            logger.debug("%sArtifact directory not found: %s", log_prefix, artifact_dir)
+            return []
+
+        try:
+            for item in await asyncio.to_thread(os.listdir, artifact_dir):
+                item_path = os.path.join(artifact_dir, item)
+                if await asyncio.to_thread(os.path.isfile, item_path) and item.isdigit():
+                    version_num = int(item)
+                    version_path = self._get_version_path(artifact_dir, version_num)
+                    metadata_path = self._get_metadata_path(artifact_dir, version_num)
+
+                    # Read metadata
+                    try:
+
+                        def _read_metadata():
+                            with open(metadata_path, encoding="utf-8") as f:
+                                return json.load(f)
+
+                        metadata = await asyncio.to_thread(_read_metadata)
+                        mime_type = metadata.get("mime_type", "application/octet-stream")
+
+                        # Get file creation time
+                        stat_info = await asyncio.to_thread(os.stat, version_path)
+                        create_time = stat_info.st_ctime
+
+                        # Create ArtifactVersion object
+                        artifact_version = ArtifactVersion(
+                            version=version_num,
+                            canonical_uri=f"file://{version_path}",
+                            mime_type=mime_type,
+                            create_time=create_time,
+                            custom_metadata={},
+                        )
+                        artifact_versions.append(artifact_version)
+
+                    except (OSError, json.JSONDecodeError) as e:
+                        logger.warning(
+                            "%sFailed to read metadata for version %d: %s",
+                            log_prefix,
+                            version_num,
+                            e,
+                        )
+                        continue
+
+        except OSError as e:
+            logger.error(
+                "%sError listing versions in directory '%s': %s",
+                log_prefix,
+                artifact_dir,
+                e,
+            )
+            return []
+
+        # Sort by version number
+        artifact_versions.sort(key=lambda av: av.version)
+        logger.debug("%sFound %d artifact versions", log_prefix, len(artifact_versions))
+        return artifact_versions
+
+    @override
+    async def get_artifact_version(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        filename: str,
+        session_id: str,
+        version: int | None = None,
+    ) -> ArtifactVersion | None:
+        """Gets the metadata for a specific version of an artifact."""
+        log_prefix = f"[FSArtifact:GetArtifactVersion:{filename}] "
+        filename = self._normalize_filename_unicode(filename)
+        artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
+
+        if not await asyncio.to_thread(os.path.isdir, artifact_dir):
+            logger.debug("%sArtifact directory not found: %s", log_prefix, artifact_dir)
+            return None
+
+        # Determine which version to load
+        load_version = version
+        if load_version is None:
+            versions = await self.list_versions(
+                app_name=app_name,
+                user_id=user_id,
+                session_id=session_id,
+                filename=filename,
+            )
+            if not versions:
+                logger.debug("%sNo versions found for artifact.", log_prefix)
+                return None
+            load_version = max(versions)
+            logger.debug("%sGetting latest version: %d", log_prefix, load_version)
+        else:
+            logger.debug("%sGetting specified version: %d", log_prefix, load_version)
+
+        version_path = self._get_version_path(artifact_dir, load_version)
+        metadata_path = self._get_metadata_path(artifact_dir, load_version)
+
+        if not await asyncio.to_thread(
+            os.path.exists, version_path
+        ) or not await asyncio.to_thread(os.path.exists, metadata_path):
+            logger.warning(
+                "%sData or metadata file missing for version %d.",
+                log_prefix,
+                load_version,
+            )
+            return None
+
+        try:
+            # Read metadata
+            def _read_metadata():
+                with open(metadata_path, encoding="utf-8") as f:
+                    return json.load(f)
+
+            metadata = await asyncio.to_thread(_read_metadata)
+            mime_type = metadata.get("mime_type", "application/octet-stream")
+
+            # Get file creation time
+            stat_info = await asyncio.to_thread(os.stat, version_path)
+            create_time = stat_info.st_ctime
+
+            # Create and return ArtifactVersion object
+            artifact_version = ArtifactVersion(
+                version=load_version,
+                canonical_uri=f"file://{version_path}",
+                mime_type=mime_type,
+                create_time=create_time,
+                custom_metadata={},
+            )
+
+            logger.info(
+                "%sRetrieved metadata for artifact '%s' version %d",
+                log_prefix,
+                filename,
+                load_version,
+            )
+            return artifact_version
+
+        except (OSError, json.JSONDecodeError) as e:
+            logger.error(
+                "%sFailed to get metadata for artifact '%s' version %d: %s",
+                log_prefix,
+                filename,
+                load_version,
+                e,
+            )
+            return None
+
     def _normalize_filename_unicode(self, filename: str) -> str:
         """
         Normalizes Unicode characters in a filename to their standard form.

solace_agent_mesh/agent/adk/artifacts/s3_artifact_service.py

@@ -10,6 +10,7 @@ import boto3
 from botocore.client import BaseClient
 from botocore.exceptions import BotoCoreError, ClientError, NoCredentialsError
 from google.adk.artifacts import BaseArtifactService
+from google.adk.artifacts.base_artifact_service import ArtifactVersion
 from google.genai import types as adk_types
 from typing_extensions import override
 
@@ -444,3 +445,165 @@ class S3ArtifactService(BaseArtifactService):
         sorted_versions = sorted(versions)
         logger.debug("%sFound versions: %s", log_prefix, sorted_versions)
         return sorted_versions
+
+    @override
+    async def list_artifact_versions(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        filename: str,
+        session_id: str,
+    ) -> list[ArtifactVersion]:
+        """Lists all versions and their metadata for a specific artifact."""
+        log_prefix = f"[S3Artifact:ListArtifactVersions:{filename}] "
+        filename = self._normalize_filename_unicode(filename)
+        app_name = app_name.strip('/')
+
+        # Get the prefix for this specific artifact (without version)
+        prefix = self._get_object_key(app_name, user_id, session_id, filename, "")
+        artifact_versions = []
+
+        try:
+
+            def _list_objects():
+                paginator = self.s3.get_paginator("list_objects_v2")
+                return paginator.paginate(Bucket=self.bucket_name, Prefix=prefix)
+
+            pages = await asyncio.to_thread(_list_objects)
+            for page in pages:
+                for obj in page.get("Contents", []):
+                    parts = obj["Key"].split("/")
+                    if len(parts) >= 5:  # scope/user/session_or_user/filename/version
+                        try:
+                            version_num = int(parts[4])
+
+                            # Get object metadata
+                            def _head_object():
+                                return self.s3.head_object(
+                                    Bucket=self.bucket_name, Key=obj["Key"]
+                                )
+
+                            metadata_response = await asyncio.to_thread(_head_object)
+
+                            # Extract information
+                            mime_type = metadata_response.get(
+                                "ContentType", "application/octet-stream"
+                            )
+                            # S3 LastModified is a datetime object, convert to timestamp
+                            create_time = obj.get("LastModified").timestamp()
+
+                            # Create ArtifactVersion object
+                            artifact_version = ArtifactVersion(
+                                version=version_num,
+                                canonical_uri=f"s3://{self.bucket_name}/{obj['Key']}",
+                                mime_type=mime_type,
+                                create_time=create_time,
+                                custom_metadata={},
+                            )
+                            artifact_versions.append(artifact_version)
+
+                        except (ValueError, ClientError) as e:
+                            logger.warning(
+                                "%sFailed to process version from key '%s': %s",
+                                log_prefix,
+                                obj["Key"],
+                                e,
+                            )
+                            continue
+
+        except ClientError as e:
+            logger.error(
+                "%sError listing versions with prefix '%s': %s",
+                log_prefix,
+                prefix,
+                e,
+            )
+            return []
+
+        # Sort by version number
+        artifact_versions.sort(key=lambda av: av.version)
+        logger.debug("%sFound %d artifact versions", log_prefix, len(artifact_versions))
+        return artifact_versions
+
+    @override
+    async def get_artifact_version(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        filename: str,
+        session_id: str,
+        version: int | None = None,
+    ) -> ArtifactVersion | None:
+        """Gets the metadata for a specific version of an artifact."""
+        log_prefix = f"[S3Artifact:GetArtifactVersion:{filename}] "
+        filename = self._normalize_filename_unicode(filename)
+        app_name = app_name.strip('/')
+
+        # Determine which version to get
+        load_version = version
+        if load_version is None:
+            versions = await self.list_versions(
+                app_name=app_name,
+                user_id=user_id,
+                session_id=session_id,
+                filename=filename,
+            )
+            if not versions:
+                logger.debug("%sNo versions found for artifact.", log_prefix)
+                return None
+            load_version = max(versions)
+            logger.debug("%sGetting latest version: %d", log_prefix, load_version)
+        else:
+            logger.debug("%sGetting specified version: %d", log_prefix, load_version)
+
+        object_key = self._get_object_key(
+            app_name, user_id, session_id, filename, load_version
+        )
+
+        try:
+
+            def _head_object():
+                return self.s3.head_object(Bucket=self.bucket_name, Key=object_key)
+
+            response = await asyncio.to_thread(_head_object)
+
+            # Extract information
+            mime_type = response.get("ContentType", "application/octet-stream")
+            # S3 LastModified is a datetime object, convert to timestamp
+            create_time = response.get("LastModified").timestamp()
+
+            # Create and return ArtifactVersion object
+            artifact_version = ArtifactVersion(
+                version=load_version,
+                canonical_uri=f"s3://{self.bucket_name}/{object_key}",
+                mime_type=mime_type,
+                create_time=create_time,
+                custom_metadata={},
+            )
+
+            logger.info(
+                "%sRetrieved metadata for artifact '%s' version %d",
+                log_prefix,
+                filename,
+                load_version,
+            )
+            return artifact_version
+
+        except ClientError as e:
+            error_code = e.response.get("Error", {}).get("Code", "Unknown")
+            if error_code == "NoSuchKey" or error_code == "404":
+                logger.debug(
+                    "%sArtifact version not found: %s", log_prefix, object_key
+                )
+                return None
+            else:
+                logger.error(
+                    "%sFailed to get metadata for artifact '%s' version %d: %s",
+                    log_prefix,
+                    filename,
+                    load_version,
+                    e,
+                )
+                return None