solace-agent-mesh 1.0.2__py3-none-any.whl → 1.0.5__py3-none-any.whl

solace_agent_mesh/__init__.py

@@ -1,5 +0,0 @@
-"""
-Solace Agent Mesh Initialization
-"""
-from .common.utils.initializer import initialize
-initialize()

solace_agent_mesh/agent/adk/filesystem_artifact_service.py

@@ -23,49 +23,40 @@ class FilesystemArtifactService(BaseArtifactService):
     """
     An artifact service implementation using the local filesystem.
 
-    Stores artifacts in a structured directory based on a configured scope
-    (namespace, app name, or custom), user ID, session ID (or 'user' namespace),
+    Stores artifacts in a structured directory based on the effective app name
+    (which represents the scope), user ID, session ID (or 'user' namespace),
     filename, and version. Metadata (like mime_type) is stored in a companion file.
     """
 
-    def __init__(self, base_path: str, scope_identifier: str):
+    def __init__(self, base_path: str):
         """
         Initializes the FilesystemArtifactService.
 
         Args:
             base_path: The root directory where all artifacts will be stored.
-            scope_identifier: The sanitized identifier representing the storage scope
-                              (e.g., sanitized namespace, app name, or custom value).
 
         Raises:
-            ValueError: If base_path or scope_identifier is not provided or the
-                        scoped base path cannot be created.
+            ValueError: If base_path is not provided or cannot be created.
         """
         if not base_path:
             raise ValueError("base_path cannot be empty for FilesystemArtifactService")
-        if not scope_identifier:
-            raise ValueError(
-                "scope_identifier cannot be empty for FilesystemArtifactService"
-            )
 
         self.base_path = os.path.abspath(base_path)
-        self.scope_identifier = scope_identifier
-        self.scope_base_path = os.path.join(self.base_path, self.scope_identifier)
 
         try:
-            os.makedirs(self.scope_base_path, exist_ok=True)
+            os.makedirs(self.base_path, exist_ok=True)
             logger.info(
-                "FilesystemArtifactService initialized. Scoped base path: %s",
-                self.scope_base_path,
+                "FilesystemArtifactService initialized. Base path: %s",
+                self.base_path,
             )
         except OSError as e:
             logger.error(
-                "Failed to create scoped base directory '%s': %s",
-                self.scope_base_path,
+                "Failed to create base directory '%s': %s",
+                self.base_path,
                 e,
             )
             raise ValueError(
-                f"Could not create or access scoped base_path '{self.scope_base_path}': {e}"
+                f"Could not create or access base_path '{self.base_path}': {e}"
             ) from e
 
     def _file_has_user_namespace(self, filename: str) -> bool:
@@ -76,10 +67,10 @@ class FilesystemArtifactService(BaseArtifactService):
         self, app_name: str, user_id: str, session_id: str, filename: str
     ) -> str:
         """
-        Constructs the directory path for a specific artifact (all versions)
-        within the configured scope.
-        The app_name parameter is ignored for path construction but kept for signature compatibility.
+        Constructs the directory path for a specific artifact (all versions).
+        The `app_name` is now the effective scope identifier, resolved by the caller.
         """
+        app_name_sanitized = os.path.basename(app_name)
         user_id_sanitized = os.path.basename(user_id)
         session_id_sanitized = os.path.basename(session_id)
         filename_sanitized = os.path.basename(filename)
@@ -87,11 +78,16 @@ class FilesystemArtifactService(BaseArtifactService):
         if self._file_has_user_namespace(filename):
             filename_dir = os.path.basename(filename.split(":", 1)[1])
             return os.path.join(
-                self.scope_base_path, user_id_sanitized, "user", filename_dir
+                self.base_path,
+                app_name_sanitized,
+                user_id_sanitized,
+                "user",
+                filename_dir,
             )
         else:
             return os.path.join(
-                self.scope_base_path,
+                self.base_path,
+                app_name_sanitized,
                 user_id_sanitized,
                 session_id_sanitized,
                 filename_sanitized,
@@ -115,7 +111,7 @@ class FilesystemArtifactService(BaseArtifactService):
         filename: str,
         artifact: adk_types.Part,
     ) -> int:
-        log_prefix = f"[FSArtifact:Save:{filename}] "
+        log_prefix = "[FSArtifact:Save] "
 
         filename = self._normalize_filename_unicode(filename)
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
@@ -192,7 +188,7 @@ class FilesystemArtifactService(BaseArtifactService):
         filename: str,
         version: Optional[int] = None,
     ) -> Optional[adk_types.Part]:
-        log_prefix = f"[FSArtifact:Load:{filename}] "
+        log_prefix = "[FSArtifact:Load] "
         filename = self._normalize_filename_unicode(filename)
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
 
@@ -271,13 +267,14 @@ class FilesystemArtifactService(BaseArtifactService):
     async def list_artifact_keys(
         self, *, app_name: str, user_id: str, session_id: str
     ) -> List[str]:
-        log_prefix = f"[FSArtifact:ListKeys] "
+        log_prefix = "[FSArtifact:ListKeys] "
         filenames = set()
+        app_name_sanitized = os.path.basename(app_name)
         user_id_sanitized = os.path.basename(user_id)
         session_id_sanitized = os.path.basename(session_id)
 
         session_base_dir = os.path.join(
-            self.scope_base_path, user_id_sanitized, session_id_sanitized
+            self.base_path, app_name_sanitized, user_id_sanitized, session_id_sanitized
         )
         if await asyncio.to_thread(os.path.isdir, session_base_dir):
             try:
@@ -293,7 +290,9 @@ class FilesystemArtifactService(BaseArtifactService):
                     e,
                 )
 
-        user_base_dir = os.path.join(self.scope_base_path, user_id_sanitized, "user")
+        user_base_dir = os.path.join(
+            self.base_path, app_name_sanitized, user_id_sanitized, "user"
+        )
         if await asyncio.to_thread(os.path.isdir, user_base_dir):
             try:
                 for item in await asyncio.to_thread(os.listdir, user_base_dir):
@@ -316,7 +315,7 @@ class FilesystemArtifactService(BaseArtifactService):
     async def delete_artifact(
         self, *, app_name: str, user_id: str, session_id: str, filename: str
     ) -> None:
-        log_prefix = f"[FSArtifact:Delete:{filename}] "
+        log_prefix = "[FSArtifact:Delete] "
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
 
         if not await asyncio.to_thread(os.path.isdir, artifact_dir):
@@ -332,9 +331,8 @@ class FilesystemArtifactService(BaseArtifactService):
             )
         except OSError as e:
             logger.error(
-                "%sError deleting artifact directory '%s': %s",
+                "%sError deleting artifact directory '%s'",
                 log_prefix,
-                artifact_dir,
                 e,
             )
 
@@ -342,7 +340,7 @@ class FilesystemArtifactService(BaseArtifactService):
     async def list_versions(
         self, *, app_name: str, user_id: str, session_id: str, filename: str
     ) -> List[int]:
-        log_prefix = f"[FSArtifact:ListVersions:{filename}] "
+        log_prefix = "[FSArtifact:ListVersions] "
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
         versions = []
 
@@ -360,12 +358,7 @@ class FilesystemArtifactService(BaseArtifactService):
                 ):
                     versions.append(int(item))
         except OSError as e:
-            logger.error(
-                "%sError listing versions in directory '%s': %s",
-                log_prefix,
-                artifact_dir,
-                e,
-            )
+            logger.error("%sError listing versions in directory '%s'", log_prefix, e)
             return []
 
         sorted_versions = sorted(versions)

solace_agent_mesh/agent/adk/services.py

@@ -4,8 +4,10 @@ Initializes ADK Services based on configuration.
 
 import os
 import re
-from typing import Dict
+from typing import Dict, Optional, List, Any
+from typing_extensions import override
 
+from google.genai import types as adk_types
 from solace_ai_connector.common.log import log
 
 from google.adk.sessions import (
@@ -35,6 +37,119 @@ except ImportError:
     TestInMemoryArtifactService = None
 
 
+class ScopedArtifactServiceWrapper(BaseArtifactService):
+    """
+    A wrapper for an artifact service that transparently applies a configured scope.
+    This ensures all artifact operations respect either 'namespace' or 'app' scoping
+    without requiring changes at the call site. It dynamically checks the component's
+    configuration on each call to support test-specific overrides.
+    """
+
+    def __init__(
+        self,
+        wrapped_service: BaseArtifactService,
+        component: Any,
+    ):
+        """
+        Initializes the ScopedArtifactServiceWrapper.
+
+        Args:
+            wrapped_service: The concrete artifact service instance (e.g., InMemory, GCS).
+            component: The component instance (agent or gateway) that owns this service.
+        """
+        self.wrapped_service = wrapped_service
+        self.component = component
+
+    def _get_scoped_app_name(self, app_name: str) -> str:
+        """
+        Determines the effective app_name for an artifact operation by dynamically
+        checking the component's configuration.
+        """
+        # The component's get_config will handle test-injected overrides.
+        # The default scope is 'namespace' as defined in the app schema.
+        scope_type = self.component.get_config("artifact_scope", "namespace")
+
+        if scope_type == "namespace":
+            # For namespace scope, the value is always the component's namespace.
+            return self.component.namespace
+
+        # For 'app' scope, use the app_name that was passed into the method, which is
+        # typically the agent_name or gateway_id.
+        return app_name
+
+    @override
+    async def save_artifact(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        filename: str,
+        artifact: adk_types.Part,
+    ) -> int:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.save_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+            artifact=artifact,
+        )
+
+    @override
+    async def load_artifact(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        filename: str,
+        version: Optional[int] = None,
+    ) -> Optional[adk_types.Part]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.load_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+            version=version,
+        )
+
+    @override
+    async def list_artifact_keys(
+        self, *, app_name: str, user_id: str, session_id: str
+    ) -> List[str]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.list_artifact_keys(
+            app_name=scoped_app_name, user_id=user_id, session_id=session_id
+        )
+
+    @override
+    async def delete_artifact(
+        self, *, app_name: str, user_id: str, session_id: str, filename: str
+    ) -> None:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        await self.wrapped_service.delete_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+        )
+        return
+
+    @override
+    async def list_versions(
+        self, *, app_name: str, user_id: str, session_id: str, filename: str
+    ) -> List[int]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.list_versions(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+        )
+
+
 def _sanitize_for_path(identifier: str) -> str:
     """Sanitizes a string to be safe for use as a directory name."""
     if not identifier:
@@ -88,7 +203,11 @@ def initialize_session_service(component) -> BaseSessionService:
 
 
 def initialize_artifact_service(component) -> BaseArtifactService:
-    """Initializes the ADK Artifact Service based on configuration."""
+    """
+    Initializes the ADK Artifact Service based on configuration.
+    This factory creates the concrete service instance and then wraps it with
+    the ScopedArtifactServiceWrapper to enforce artifact scoping rules dynamically.
+    """
     config: Dict = component.get_config("artifact_service", {"type": "memory"})
     service_type = config.get("type", "memory").lower()
     log.info(
@@ -97,8 +216,9 @@ def initialize_artifact_service(component) -> BaseArtifactService:
         service_type,
     )
 
+    concrete_service: BaseArtifactService
     if service_type == "memory":
-        return InMemoryArtifactService()
+        concrete_service = InMemoryArtifactService()
     elif service_type == "gcs":
         bucket_name = config.get("bucket_name")
         if not bucket_name:
@@ -107,9 +227,11 @@ def initialize_artifact_service(component) -> BaseArtifactService:
             )
         try:
             gcs_args = {
-                k: v for k, v in config.items() if k not in ["type", "bucket_name"]
+                k: v
+                for k, v in config.items()
+                if k not in ["type", "bucket_name", "artifact_scope"]
             }
-            return GcsArtifactService(bucket_name=bucket_name, **gcs_args)
+            concrete_service = GcsArtifactService(bucket_name=bucket_name, **gcs_args)
         except ImportError:
             log.error(
                 "%s google-cloud-storage not installed. Please install 'google-adk[gcs]' or 'google-cloud-storage'.",
@@ -123,60 +245,8 @@ def initialize_artifact_service(component) -> BaseArtifactService:
                 f"{component.log_identifier} 'base_path' is required for filesystem artifact service."
             )
 
-        artifact_scope = config.get("artifact_scope", "namespace").lower()
-        scope_identifier_raw = None
-
-        if artifact_scope == "app":
-            app_instance = component.get_app()
-            if not app_instance or not app_instance.name:
-                raise ValueError(
-                    f"{component.log_identifier} Cannot determine app name for 'app' scope."
-                )
-            scope_identifier_raw = app_instance.name
-            log.info(
-                "%s Using 'app' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        elif artifact_scope == "namespace":
-            scope_identifier_raw = component.get_config("namespace")
-            log.info(
-                "%s Using 'namespace' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        elif artifact_scope == "custom":
-            scope_identifier_raw = config.get("artifact_scope_value")
-            if not scope_identifier_raw:
-                raise ValueError(
-                    f"{component.log_identifier} 'artifact_scope_value' is required when artifact_scope is 'custom'."
-                )
-            log.info(
-                "%s Using 'custom' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        else:
-            raise ValueError(
-                f"{component.log_identifier} Invalid 'artifact_scope' value: {artifact_scope}"
-            )
-
-        if not scope_identifier_raw:
-            raise ValueError(
-                f"{component.log_identifier} Failed to determine scope identifier for filesystem artifacts."
-            )
-
-        scope_identifier_sanitized = _sanitize_for_path(scope_identifier_raw)
-        log.info(
-            "%s Sanitized scope identifier: %s",
-            component.log_identifier,
-            scope_identifier_sanitized,
-        )
-
         try:
-            return FilesystemArtifactService(
-                base_path=base_path, scope_identifier=scope_identifier_sanitized
-            )
+            concrete_service = FilesystemArtifactService(base_path=base_path)
         except Exception as e:
             log.error(
                 "%s Failed to initialize FilesystemArtifactService: %s",
@@ -196,12 +266,23 @@ def initialize_artifact_service(component) -> BaseArtifactService:
             "%s Using TestInMemoryArtifactService for testing.",
             component.log_identifier,
         )
-        return TestInMemoryArtifactService()
+        concrete_service = TestInMemoryArtifactService()
     else:
         raise ValueError(
             f"{component.log_identifier} Unsupported artifact service type: {service_type}"
         )
 
+    # Wrap the concrete service to enforce scoping dynamically.
+    # The wrapper will query the component's config at runtime.
+    log.info(
+        "%s Wrapping artifact service with dynamic ScopedArtifactServiceWrapper.",
+        component.log_identifier,
+    )
+    return ScopedArtifactServiceWrapper(
+        wrapped_service=concrete_service,
+        component=component,
+    )
+
 
 def initialize_memory_service(component) -> BaseMemoryService:
     """Initializes the ADK Memory Service based on configuration."""

solace_agent_mesh/agent/protocol/event_handlers.py

@@ -32,6 +32,7 @@ from ...common.types import (
     TaskStatus,
     TaskState,
     DataPart,
+    TextPart,
     A2ARequest,
 )
 from ...common.a2a_protocol import (
@@ -44,6 +45,7 @@ from ...common.a2a_protocol import (
     _extract_text_from_parts,
 )
 from ...agent.utils.artifact_helpers import (
+    generate_artifact_metadata_summary,
     load_artifact_content_or_metadata,
 )
 from ...agent.adk.runner import run_adk_async_task_thread_wrapper
@@ -57,114 +59,6 @@ from google.adk.events import Event as ADKEvent
 from google.genai import types as adk_types
 
 
-async def _format_artifact_summary_from_manifest(
-    component: "SamAgentComponent",
-    produced_artifacts: List[Dict[str, Any]],
-    peer_agent_name: str,
-    correlation_data: Dict[str, Any],
-) -> str:
-    """
-    Loads metadata for a list of produced artifacts and formats it into a
-    human-readable YAML summary string.
-    """
-    if not produced_artifacts:
-        return ""
-
-    artifact_summary_lines = [
-        f"Peer agent `{peer_agent_name}` created {len(produced_artifacts)} artifact(s):"
-    ]
-
-    original_task_context = correlation_data.get("original_task_context", {})
-    user_id = original_task_context.get("user_id")
-    session_id = original_task_context.get("session_id")
-
-    if not (component.artifact_service and user_id and session_id):
-        log.warning(
-            "%s Cannot load artifact metadata: missing artifact_service or context.",
-            component.log_identifier,
-        )
-        for artifact_ref in produced_artifacts:
-            artifact_summary_lines.append(
-                f"- `{artifact_ref.get('filename')}` (v{artifact_ref.get('version')})"
-            )
-        return "\n".join(artifact_summary_lines)
-
-    peer_agent_name_for_artifact = peer_agent_name
-    if (
-        not peer_agent_name_for_artifact
-        or peer_agent_name_for_artifact == "A peer agent"
-    ):
-        log.warning(
-            "%s Peer agent name not in task metadata, using self agent name for artifact loading.",
-            component.log_identifier,
-        )
-        peer_agent_name_for_artifact = component.agent_name
-
-    for artifact_ref in produced_artifacts:
-        filename = artifact_ref.get("filename")
-        version = artifact_ref.get("version")
-        if not filename or version is None:
-            continue
-
-        try:
-            metadata_result = await load_artifact_content_or_metadata(
-                artifact_service=component.artifact_service,
-                app_name=peer_agent_name_for_artifact,
-                user_id=user_id,
-                session_id=session_id,
-                filename=filename,
-                version=version,
-                load_metadata_only=True,
-            )
-            if metadata_result.get("status") == "success":
-                metadata = metadata_result.get("metadata", {})
-                TRUNCATION_LIMIT_BYTES = 1024
-                TRUNCATION_MESSAGE = "\n... [truncated] ..."
-
-                try:
-                    formatted_metadata_str = yaml.safe_dump(
-                        metadata,
-                        default_flow_style=False,
-                        sort_keys=False,
-                        allow_unicode=True,
-                    )
-
-                    if (
-                        len(formatted_metadata_str.encode("utf-8"))
-                        > TRUNCATION_LIMIT_BYTES
-                    ):
-                        cutoff = TRUNCATION_LIMIT_BYTES - len(
-                            TRUNCATION_MESSAGE.encode("utf-8")
-                        )
-                        formatted_metadata_str = (
-                            formatted_metadata_str[:cutoff] + TRUNCATION_MESSAGE
-                        )
-
-                    summary_line = f"- `{filename}` (v{version}):\n  ```yaml\n{formatted_metadata_str}\n  ```"
-                    artifact_summary_lines.append(summary_line)
-                except Exception as e_format:
-                    log.error(
-                        "Error formatting metadata for %s v%s: %s",
-                        filename,
-                        version,
-                        e_format,
-                    )
-                    artifact_summary_lines.append(
-                        f"- `{filename}` (v{version}): Error formatting metadata."
-                    )
-            else:
-                artifact_summary_lines.append(
-                    f"- `{filename}` (v{version}): Could not load metadata."
-                )
-        except Exception as e_meta:
-            log.error(
-                "Error loading metadata for %s v%s: %s", filename, version, e_meta
-            )
-            artifact_summary_lines.append(
-                f"- `{filename}` (v{version}): Error loading metadata."
-            )
-
-    return "\n".join(artifact_summary_lines)
 
 
 def _register_peer_artifacts_in_parent_context(
@@ -610,8 +504,51 @@ async def handle_a2a_request(component, message: SolaceMessage):
                 logical_task_id,
             )
 
+            a2a_message_for_adk = a2a_request.params.message
+            invoked_artifacts = (
+                a2a_message_for_adk.metadata.get("invoked_with_artifacts", [])
+                if a2a_message_for_adk.metadata
+                else []
+            )
+
+            if invoked_artifacts:
+                log.info(
+                    "%s Task %s invoked with %d artifact(s). Preparing context from metadata.",
+                    component.log_identifier,
+                    task_id,
+                    len(invoked_artifacts),
+                )
+                header_text = (
+                    "The user has provided the following artifacts as context for your task. "
+                    "Use the information contained within their metadata to complete your objective."
+                )
+                artifact_summary = await generate_artifact_metadata_summary(
+                    component=component,
+                    artifact_identifiers=invoked_artifacts,
+                    user_id=user_id,
+                    session_id=effective_session_id,
+                    app_name=agent_name,
+                    header_text=header_text,
+                )
+
+                task_description = _extract_text_from_parts(
+                    a2a_message_for_adk.parts
+                )
+                final_prompt = f"{task_description}\n\n{artifact_summary}"
+
+                a2a_message_for_adk = A2AMessage(
+                    role="user",
+                    parts=[TextPart(text=final_prompt)],
+                    metadata=a2a_message_for_adk.metadata,
+                )
+                log.debug(
+                    "%s Generated new prompt for task %s with artifact context.",
+                    component.log_identifier,
+                    task_id,
+                )
+
             adk_content = translate_a2a_to_adk_content(
-                a2a_request.params.message, component.log_identifier
+                a2a_message_for_adk, component.log_identifier
             )
 
             adk_session = await component.session_service.get_session(
@@ -1284,14 +1221,31 @@ async def handle_a2a_response(component, message: SolaceMessage):
                                 peer_agent_name = task_obj.metadata.get(
                                     "agent_name", "A peer agent"
                                 )
-                                artifact_summary = (
-                                    await _format_artifact_summary_from_manifest(
-                                        component,
-                                        produced_artifacts,
-                                        peer_agent_name,
-                                        correlation_data,
-                                    )
+                                original_task_context = correlation_data.get(
+                                    "original_task_context", {}
                                 )
+                                user_id = original_task_context.get("user_id")
+                                session_id = original_task_context.get("session_id")
+
+                                header_text = f"Peer agent `{peer_agent_name}` created {len(produced_artifacts)} artifact(s):"
+
+                                if user_id and session_id:
+                                    artifact_summary = (
+                                        await generate_artifact_metadata_summary(
+                                            component=component,
+                                            artifact_identifiers=produced_artifacts,
+                                            user_id=user_id,
+                                            session_id=session_id,
+                                            app_name=peer_agent_name,
+                                            header_text=header_text,
+                                        )
+                                    )
+                                else:
+                                    log.warning(
+                                        "%s Could not generate artifact summary: missing user_id or session_id in correlation data.",
+                                        log_retrigger,
+                                    )
+                                    artifact_summary = ""
                                 # Bubble up the peer's artifacts to the parent context
                                 _register_peer_artifacts_in_parent_context(
                                     task_context, task_obj, log_retrigger