diff --git a/tests/unit/vertexai/genai/replays/test_structured_memories.py b/tests/unit/vertexai/genai/replays/test_structured_memories.py new file mode 100644 index 0000000000..035a9a71a3 --- /dev/null +++ b/tests/unit/vertexai/genai/replays/test_structured_memories.py @@ -0,0 +1,100 @@ +# 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. +# +# pylint: disable=protected-access,bad-continuation,missing-function-docstring + +from tests.unit.vertexai.genai.replays import pytest_helper +from vertexai._genai import types + + +def test_generate_and_retrieve_profile(client): + # TODO: Use prod once available. + client._api_client._http_options.base_url = ( + "https://us-central1-autopush-aiplatform.sandbox.googleapis.com" + ) + customization_config = {"disable_natural_language_memories": True} + memory_bank_customization_config = types.MemoryBankCustomizationConfig( + **customization_config + ) + structured_memory_config = { + "scope_keys": ["user_id"], + "schema_configs": [ + { + "id": "user-profile", + "schema": { + "properties": { + "name": {"description": "User's name", "type": "string"} + }, + "type": "object", + }, + } + ], + } + structured_memory_config_obj = types.StructuredMemoryConfig( + **structured_memory_config + ) + agent_engine = client.agent_engines.create( + config={ + "context_spec": { + "memory_bank_config": { + "customization_configs": [memory_bank_customization_config], + "structured_memory_configs": [structured_memory_config_obj], + }, + }, + "http_options": {"api_version": "v1beta1"}, + }, + ) + try: + agent_engine = client.agent_engines.get(name=agent_engine.api_resource.name) + memory_bank_config = agent_engine.api_resource.context_spec.memory_bank_config + assert memory_bank_config.customization_configs == [ + memory_bank_customization_config + ] + assert memory_bank_config.structured_memory_configs == [ + structured_memory_config_obj + ] + + scope = {"user_id": "123"} + client.agent_engines.memories.generate( + name=agent_engine.api_resource.name, + scope=scope, + direct_contents_source={ + "events": [{"content": {"parts": [{"text": "My name is Kim."}]}}] + }, + ) + memories = list( + client.agent_engines.memories.retrieve( + name=agent_engine.api_resource.name, + scope=scope, + config={"memory_types": ["STRUCTURED_PROFILE"]}, + ) + ) + assert len(memories) >= 1 + assert memories[0].memory.structured_content is not None + + response = client.agent_engines.memories.retrieve_profiles( + name=agent_engine.api_resource.name, scope=scope + ) + assert len(response.profiles) == 1 + + finally: + # Clean up resources. + client.agent_engines.delete(name=agent_engine.api_resource.name, force=True) + + +pytestmark = pytest_helper.setup( + file=__file__, + globals_for_file=globals(), + test_method="agent_engines.retrieve_profiles", +) diff --git a/vertexai/_genai/memories.py b/vertexai/_genai/memories.py index 2d4b1b180c..018b62edf1 100644 --- a/vertexai/_genai/memories.py +++ b/vertexai/_genai/memories.py @@ -329,6 +329,9 @@ def _RetrieveAgentEngineMemoriesConfig_to_vertex( [item for item in getv(from_object, ["filter_groups"])], ) + if getv(from_object, ["memory_types"]) is not None: + setv(parent_object, ["memoryTypes"], getv(from_object, ["memory_types"])) + return to_object @@ -365,6 +368,20 @@ def _RetrieveAgentEngineMemoriesRequestParameters_to_vertex( return to_object +def _RetrieveMemoryProfilesRequestParameters_to_vertex( + from_object: Union[dict[str, Any], object], + parent_object: Optional[dict[str, Any]] = None, +) -> dict[str, Any]: + to_object: dict[str, Any] = {} + if getv(from_object, ["name"]) is not None: + setv(to_object, ["_url", "name"], getv(from_object, ["name"])) + + if getv(from_object, ["scope"]) is not None: + setv(to_object, ["scope"], getv(from_object, ["scope"])) + + return to_object + + def _RollbackAgentEngineMemoryRequestParameters_to_vertex( from_object: Union[dict[str, Any], object], parent_object: Optional[dict[str, Any]] = None, @@ -935,6 +952,72 @@ def _retrieve( self._api_client._verify_response(return_value) return return_value + def retrieve_profiles( + self, + *, + name: str, + scope: dict[str, str], + config: Optional[types.RetrieveMemoryProfilesConfigOrDict] = None, + ) -> types.RetrieveProfilesResponse: + """ + Retrieves memory profiles for an Agent Engine. + + Args: + name (str): Required. A fully-qualified resource name or ID such as + "projects/123/locations/us-central1/reasoningEngines/456". + scope (dict[str, str]): Required. The scope of the memories to retrieve. + A memory must have exactly the same scope as the scope provided here + to be retrieved (i.e. same keys and values). Order does not matter, + but it is case-sensitive. + + """ + + parameter_model = types._RetrieveMemoryProfilesRequestParameters( + name=name, + scope=scope, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError("This method is only supported in the Vertex AI client.") + else: + request_dict = _RetrieveMemoryProfilesRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/memories:retrieveProfiles".format_map(request_url_dict) + else: + path = "{name}/memories:retrieveProfiles" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = self._api_client.request("post", path, request_dict, http_options) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RetrieveProfilesResponse._from_response( + response=response_dict, kwargs=parameter_model.model_dump() + ) + + self._api_client._verify_response(return_value) + return return_value + def _rollback( self, *, @@ -1909,6 +1992,74 @@ async def _retrieve( self._api_client._verify_response(return_value) return return_value + async def retrieve_profiles( + self, + *, + name: str, + scope: dict[str, str], + config: Optional[types.RetrieveMemoryProfilesConfigOrDict] = None, + ) -> types.RetrieveProfilesResponse: + """ + Retrieves memory profiles for an Agent Engine. + + Args: + name (str): Required. A fully-qualified resource name or ID such as + "projects/123/locations/us-central1/reasoningEngines/456". + scope (dict[str, str]): Required. The scope of the memories to retrieve. + A memory must have exactly the same scope as the scope provided here + to be retrieved (i.e. same keys and values). Order does not matter, + but it is case-sensitive. + + """ + + parameter_model = types._RetrieveMemoryProfilesRequestParameters( + name=name, + scope=scope, + config=config, + ) + + request_url_dict: Optional[dict[str, str]] + if not self._api_client.vertexai: + raise ValueError("This method is only supported in the Vertex AI client.") + else: + request_dict = _RetrieveMemoryProfilesRequestParameters_to_vertex( + parameter_model + ) + request_url_dict = request_dict.get("_url") + if request_url_dict: + path = "{name}/memories:retrieveProfiles".format_map(request_url_dict) + else: + path = "{name}/memories:retrieveProfiles" + + query_params = request_dict.get("_query") + if query_params: + path = f"{path}?{urlencode(query_params)}" + # TODO: remove the hack that pops config. + request_dict.pop("config", None) + + http_options: Optional[types.HttpOptions] = None + if ( + parameter_model.config is not None + and parameter_model.config.http_options is not None + ): + http_options = parameter_model.config.http_options + + request_dict = _common.convert_to_dict(request_dict) + request_dict = _common.encode_unserializable_types(request_dict) + + response = await self._api_client.async_request( + "post", path, request_dict, http_options + ) + + response_dict = {} if not response.body else json.loads(response.body) + + return_value = types.RetrieveProfilesResponse._from_response( + response=response_dict, kwargs=parameter_model.model_dump() + ) + + self._api_client._verify_response(return_value) + return return_value + async def _rollback( self, *, diff --git a/vertexai/_genai/types/__init__.py b/vertexai/_genai/types/__init__.py index 472ae09f06..51f8ed17c4 100644 --- a/vertexai/_genai/types/__init__.py +++ b/vertexai/_genai/types/__init__.py @@ -94,6 +94,7 @@ from .common import _QueryAgentEngineRequestParameters from .common import _RestoreVersionRequestParameters from .common import _RetrieveAgentEngineMemoriesRequestParameters +from .common import _RetrieveMemoryProfilesRequestParameters from .common import _RollbackAgentEngineMemoryRequestParameters from .common import _RunQueryJobAgentEngineConfig from .common import _RunQueryJobAgentEngineConfigDict @@ -689,12 +690,19 @@ from .common import MemoryMetadataValueDict from .common import MemoryMetadataValueOrDict from .common import MemoryOrDict +from .common import MemoryProfile +from .common import MemoryProfileDict +from .common import MemoryProfileOrDict from .common import MemoryRevision from .common import MemoryRevisionDict from .common import MemoryRevisionOrDict +from .common import MemoryStructuredContent +from .common import MemoryStructuredContentDict +from .common import MemoryStructuredContentOrDict from .common import MemoryTopicId from .common import MemoryTopicIdDict from .common import MemoryTopicIdOrDict +from .common import MemoryType from .common import Message from .common import MessageDict from .common import Metadata @@ -886,6 +894,12 @@ from .common import RetrieveMemoriesResponseRetrievedMemory from .common import RetrieveMemoriesResponseRetrievedMemoryDict from .common import RetrieveMemoriesResponseRetrievedMemoryOrDict +from .common import RetrieveMemoryProfilesConfig +from .common import RetrieveMemoryProfilesConfigDict +from .common import RetrieveMemoryProfilesConfigOrDict +from .common import RetrieveProfilesResponse +from .common import RetrieveProfilesResponseDict +from .common import RetrieveProfilesResponseOrDict from .common import RollbackAgentEngineMemoryConfig from .common import RollbackAgentEngineMemoryConfigDict from .common import RollbackAgentEngineMemoryConfigOrDict @@ -1041,6 +1055,12 @@ from .common import SessionOrDict from .common import State from .common import Strategy +from .common import StructuredMemoryConfig +from .common import StructuredMemoryConfigDict +from .common import StructuredMemoryConfigOrDict +from .common import StructuredMemoryConfigSchemaConfig +from .common import StructuredMemoryConfigSchemaConfigDict +from .common import StructuredMemoryConfigSchemaConfigOrDict from .common import SummaryMetric from .common import SummaryMetricDict from .common import SummaryMetricOrDict @@ -1653,6 +1673,12 @@ "ReasoningEngineContextSpecMemoryBankConfigTtlConfig", "ReasoningEngineContextSpecMemoryBankConfigTtlConfigDict", "ReasoningEngineContextSpecMemoryBankConfigTtlConfigOrDict", + "StructuredMemoryConfigSchemaConfig", + "StructuredMemoryConfigSchemaConfigDict", + "StructuredMemoryConfigSchemaConfigOrDict", + "StructuredMemoryConfig", + "StructuredMemoryConfigDict", + "StructuredMemoryConfigOrDict", "ReasoningEngineContextSpecMemoryBankConfig", "ReasoningEngineContextSpecMemoryBankConfigDict", "ReasoningEngineContextSpecMemoryBankConfigOrDict", @@ -1743,6 +1769,9 @@ "AgentEngineMemoryConfig", "AgentEngineMemoryConfigDict", "AgentEngineMemoryConfigOrDict", + "MemoryStructuredContent", + "MemoryStructuredContentDict", + "MemoryStructuredContentOrDict", "Memory", "MemoryDict", "MemoryOrDict", @@ -1812,6 +1841,15 @@ "RetrieveMemoriesResponse", "RetrieveMemoriesResponseDict", "RetrieveMemoriesResponseOrDict", + "RetrieveMemoryProfilesConfig", + "RetrieveMemoryProfilesConfigDict", + "RetrieveMemoryProfilesConfigOrDict", + "MemoryProfile", + "MemoryProfileDict", + "MemoryProfileOrDict", + "RetrieveProfilesResponse", + "RetrieveProfilesResponseDict", + "RetrieveProfilesResponseOrDict", "RollbackAgentEngineMemoryConfig", "RollbackAgentEngineMemoryConfigDict", "RollbackAgentEngineMemoryConfigOrDict", @@ -2197,6 +2235,7 @@ "Type", "JobState", "ManagedTopicEnum", + "MemoryType", "IdentityType", "AgentServerMode", "Operator", @@ -2271,6 +2310,7 @@ "_GetAgentEngineMemoryOperationParameters", "_GetAgentEngineGenerateMemoriesOperationParameters", "_RetrieveAgentEngineMemoriesRequestParameters", + "_RetrieveMemoryProfilesRequestParameters", "_RollbackAgentEngineMemoryRequestParameters", "_UpdateAgentEngineMemoryRequestParameters", "_PurgeAgentEngineMemoriesRequestParameters", diff --git a/vertexai/_genai/types/common.py b/vertexai/_genai/types/common.py index 2d9f4b50ce..c95bf9a471 100644 --- a/vertexai/_genai/types/common.py +++ b/vertexai/_genai/types/common.py @@ -258,6 +258,17 @@ class ManagedTopicEnum(_common.CaseInSensitiveEnum): """Information that the user explicitly requested to remember or forget.""" +class MemoryType(_common.CaseInSensitiveEnum): + """The type of the memory.""" + + MEMORY_TYPE_UNSPECIFIED = "MEMORY_TYPE_UNSPECIFIED" + """Represents an unspecified memory type. This value should not be used.""" + NATURAL_LANGUAGE_COLLECTION = "NATURAL_LANGUAGE_COLLECTION" + """Indicates belonging to a collection of natural language memories.""" + STRUCTURED_PROFILE = "STRUCTURED_PROFILE" + """Indicates belonging to a structured profile.""" + + class IdentityType(_common.CaseInSensitiveEnum): """The identity type to use for the Reasoning Engine. If not specified, the `service_account` field will be used if set, otherwise the default Vertex AI Reasoning Engine Service Agent in the project will be used.""" @@ -6610,6 +6621,10 @@ class MemoryBankCustomizationConfig(_common.BaseModel): description="""Optional. Represents configuration for customizing how memories are consolidated together.""", ) ) + disable_natural_language_memories: Optional[bool] = Field( + default=None, + description="""Optional. Indicates whether natural language memory generation should be disabled for all requests. By default, natural language memory generation is enabled. Set this to `true` when you only want to generate structured memories.""", + ) class MemoryBankCustomizationConfigDict(TypedDict, total=False): @@ -6632,6 +6647,9 @@ class MemoryBankCustomizationConfigDict(TypedDict, total=False): consolidation_config: Optional[MemoryBankCustomizationConfigConsolidationConfigDict] """Optional. Represents configuration for customizing how memories are consolidated together.""" + disable_natural_language_memories: Optional[bool] + """Optional. Indicates whether natural language memory generation should be disabled for all requests. By default, natural language memory generation is enabled. Set this to `true` when you only want to generate structured memories.""" + MemoryBankCustomizationConfigOrDict = Union[ MemoryBankCustomizationConfig, MemoryBankCustomizationConfigDict @@ -6768,6 +6786,67 @@ class ReasoningEngineContextSpecMemoryBankConfigTtlConfigDict(TypedDict, total=F ] +class StructuredMemoryConfigSchemaConfig(_common.BaseModel): + """Represents the OpenAPI schema of the structured memories.""" + + id: Optional[str] = Field( + default=None, + description="""Required. Represents the ID of the schema. Must be 1-63 characters, start with a lowercase letter, and consist of lowercase letters, numbers, and hyphens.""", + ) + schema: Optional[genai_types.Schema] = Field( + default=None, + description="""Required. Represents the OpenAPI schema of the structured memories. The schema `type` cannot be `ARRAY` when `memory_type` is `STRUCTURED_PROFILE`.""", + ) + memory_type: Optional[MemoryType] = Field( + default=None, + description="""Optional. Represents the type of the structured memories associated with the schema. If not set, then `STRUCTURED_PROFILE` will be used.""", + ) + + +class StructuredMemoryConfigSchemaConfigDict(TypedDict, total=False): + """Represents the OpenAPI schema of the structured memories.""" + + id: Optional[str] + """Required. Represents the ID of the schema. Must be 1-63 characters, start with a lowercase letter, and consist of lowercase letters, numbers, and hyphens.""" + + schema: Optional[genai_types.SchemaDict] + """Required. Represents the OpenAPI schema of the structured memories. The schema `type` cannot be `ARRAY` when `memory_type` is `STRUCTURED_PROFILE`.""" + + memory_type: Optional[MemoryType] + """Optional. Represents the type of the structured memories associated with the schema. If not set, then `STRUCTURED_PROFILE` will be used.""" + + +StructuredMemoryConfigSchemaConfigOrDict = Union[ + StructuredMemoryConfigSchemaConfig, StructuredMemoryConfigSchemaConfigDict +] + + +class StructuredMemoryConfig(_common.BaseModel): + """Represents configuration for organizing structured memories for a particular scope.""" + + scope_keys: Optional[list[str]] = Field( + default=None, + description="""Optional. Represents the scope keys (i.e. 'user_id') for which to use this config. A request's scope must include all of the provided keys for the config to be used (order does not matter). If empty, then the config will be used for all requests that do not have a more specific config. Only one default config is allowed per Memory Bank.""", + ) + schema_configs: Optional[list[StructuredMemoryConfigSchemaConfig]] = Field( + default=None, + description="""Optional. Represents configuration of the structured memories' schemas.""", + ) + + +class StructuredMemoryConfigDict(TypedDict, total=False): + """Represents configuration for organizing structured memories for a particular scope.""" + + scope_keys: Optional[list[str]] + """Optional. Represents the scope keys (i.e. 'user_id') for which to use this config. A request's scope must include all of the provided keys for the config to be used (order does not matter). If empty, then the config will be used for all requests that do not have a more specific config. Only one default config is allowed per Memory Bank.""" + + schema_configs: Optional[list[StructuredMemoryConfigSchemaConfigDict]] + """Optional. Represents configuration of the structured memories' schemas.""" + + +StructuredMemoryConfigOrDict = Union[StructuredMemoryConfig, StructuredMemoryConfigDict] + + class ReasoningEngineContextSpecMemoryBankConfig(_common.BaseModel): """Specification for a Memory Bank.""" @@ -6795,6 +6874,10 @@ class ReasoningEngineContextSpecMemoryBankConfig(_common.BaseModel): default=None, description="""Optional. Configuration for automatic TTL ("time-to-live") of the memories in the Memory Bank. If not set, TTL will not be applied automatically. The TTL can be explicitly set by modifying the `expire_time` of each Memory resource.""", ) + structured_memory_configs: Optional[list[StructuredMemoryConfig]] = Field( + default=None, + description="""Optional. Configuration for organizing structured memories for a particular scope.""", + ) class ReasoningEngineContextSpecMemoryBankConfigDict(TypedDict, total=False): @@ -6819,6 +6902,9 @@ class ReasoningEngineContextSpecMemoryBankConfigDict(TypedDict, total=False): ttl_config: Optional[ReasoningEngineContextSpecMemoryBankConfigTtlConfigDict] """Optional. Configuration for automatic TTL ("time-to-live") of the memories in the Memory Bank. If not set, TTL will not be applied automatically. The TTL can be explicitly set by modifying the `expire_time` of each Memory resource.""" + structured_memory_configs: Optional[list[StructuredMemoryConfigDict]] + """Optional. Configuration for organizing structured memories for a particular scope.""" + ReasoningEngineContextSpecMemoryBankConfigOrDict = Union[ ReasoningEngineContextSpecMemoryBankConfig, @@ -8647,6 +8733,34 @@ class _CreateAgentEngineMemoryRequestParametersDict(TypedDict, total=False): ] +class MemoryStructuredContent(_common.BaseModel): + """Represents the structured value of the memory.""" + + data: Optional[dict[str, Any]] = Field( + default=None, + description="""Required. Represents the structured value of the memory.""", + ) + schema_id: Optional[str] = Field( + default=None, + description="""Required. Represents the schema ID for which this structured memory belongs to.""", + ) + + +class MemoryStructuredContentDict(TypedDict, total=False): + """Represents the structured value of the memory.""" + + data: Optional[dict[str, Any]] + """Required. Represents the structured value of the memory.""" + + schema_id: Optional[str] + """Required. Represents the schema ID for which this structured memory belongs to.""" + + +MemoryStructuredContentOrDict = Union[ + MemoryStructuredContent, MemoryStructuredContentDict +] + + class Memory(_common.BaseModel): """A memory.""" @@ -8707,6 +8821,14 @@ class Memory(_common.BaseModel): default=None, description="""Output only. Timestamp when this Memory was most recently updated.""", ) + memory_type: Optional[MemoryType] = Field( + default=None, + description="""Optional. Represents the type of the memory. If not set, the `NATURAL_LANGUAGE_COLLECTION` type is used. If `STRUCTURED_COLLECTION` or `STRUCTURED_PROFILE` is used, then `structured_data` must be provided.""", + ) + structured_content: Optional[MemoryStructuredContent] = Field( + default=None, + description="""Optional. Represents the structured content of the memory.""", + ) class MemoryDict(TypedDict, total=False): @@ -8757,6 +8879,12 @@ class MemoryDict(TypedDict, total=False): update_time: Optional[datetime.datetime] """Output only. Timestamp when this Memory was most recently updated.""" + memory_type: Optional[MemoryType] + """Optional. Represents the type of the memory. If not set, the `NATURAL_LANGUAGE_COLLECTION` type is used. If `STRUCTURED_COLLECTION` or `STRUCTURED_PROFILE` is used, then `structured_data` must be provided.""" + + structured_content: Optional[MemoryStructuredContentDict] + """Optional. Represents the structured content of the memory.""" + MemoryOrDict = Union[Memory, MemoryDict] @@ -9662,6 +9790,13 @@ class RetrieveAgentEngineMemoriesConfig(_common.BaseModel): metadata.author = "agent 321"))`. """, ) + memory_types: Optional[list[MemoryType]] = Field( + default=None, + description="""Specifies the types of memories to retrieve. If this field is empty + or not provided, the request will default to retrieving only memories of + type `NATURAL_LANGUAGE_COLLECTION`. If populated, the request will + retrieve memories matching any of the specified `MemoryType` values.""", + ) class RetrieveAgentEngineMemoriesConfigDict(TypedDict, total=False): @@ -9696,6 +9831,12 @@ class RetrieveAgentEngineMemoriesConfigDict(TypedDict, total=False): metadata.author = "agent 321"))`. """ + memory_types: Optional[list[MemoryType]] + """Specifies the types of memories to retrieve. If this field is empty + or not provided, the request will default to retrieving only memories of + type `NATURAL_LANGUAGE_COLLECTION`. If populated, the request will + retrieve memories matching any of the specified `MemoryType` values.""" + RetrieveAgentEngineMemoriesConfigOrDict = Union[ RetrieveAgentEngineMemoriesConfig, RetrieveAgentEngineMemoriesConfigDict @@ -9819,6 +9960,121 @@ class RetrieveMemoriesResponseDict(TypedDict, total=False): ] +class RetrieveMemoryProfilesConfig(_common.BaseModel): + """Config for retrieving memory profiles.""" + + http_options: Optional[genai_types.HttpOptions] = Field( + default=None, description="""Used to override HTTP request options.""" + ) + + +class RetrieveMemoryProfilesConfigDict(TypedDict, total=False): + """Config for retrieving memory profiles.""" + + http_options: Optional[genai_types.HttpOptionsDict] + """Used to override HTTP request options.""" + + +RetrieveMemoryProfilesConfigOrDict = Union[ + RetrieveMemoryProfilesConfig, RetrieveMemoryProfilesConfigDict +] + + +class _RetrieveMemoryProfilesRequestParameters(_common.BaseModel): + """Parameters for retrieving agent engine memory profiles.""" + + name: Optional[str] = Field( + default=None, + description="""Name of the agent engine to retrieve memory profiles from.""", + ) + scope: Optional[dict[str, str]] = Field( + default=None, + description="""The scope of the memories to retrieve. + + A memory must have exactly the same scope as the scope provided here to be + retrieved (i.e. same keys and values). Order does not matter, but it is + case-sensitive.""", + ) + config: Optional[RetrieveMemoryProfilesConfig] = Field( + default=None, description="""""" + ) + + +class _RetrieveMemoryProfilesRequestParametersDict(TypedDict, total=False): + """Parameters for retrieving agent engine memory profiles.""" + + name: Optional[str] + """Name of the agent engine to retrieve memory profiles from.""" + + scope: Optional[dict[str, str]] + """The scope of the memories to retrieve. + + A memory must have exactly the same scope as the scope provided here to be + retrieved (i.e. same keys and values). Order does not matter, but it is + case-sensitive.""" + + config: Optional[RetrieveMemoryProfilesConfigDict] + """""" + + +_RetrieveMemoryProfilesRequestParametersOrDict = Union[ + _RetrieveMemoryProfilesRequestParameters, + _RetrieveMemoryProfilesRequestParametersDict, +] + + +class MemoryProfile(_common.BaseModel): + """A memory profile.""" + + schema_id: Optional[str] = Field( + default=None, + description="""Represents the ID of the schema. This ID corresponds to the `schema_id` defined inside the SchemaConfig, under StructuredMemoryCustomizationConfig.""", + ) + profile: Optional[dict[str, Any]] = Field( + default=None, description="""Represents the profile data.""" + ) + + +class MemoryProfileDict(TypedDict, total=False): + """A memory profile.""" + + schema_id: Optional[str] + """Represents the ID of the schema. This ID corresponds to the `schema_id` defined inside the SchemaConfig, under StructuredMemoryCustomizationConfig.""" + + profile: Optional[dict[str, Any]] + """Represents the profile data.""" + + +MemoryProfileOrDict = Union[MemoryProfile, MemoryProfileDict] + + +class RetrieveProfilesResponse(_common.BaseModel): + """The response for retrieving memory profiles.""" + + memory_profiles: Optional[dict[str, MemoryProfile]] = Field( + default=None, description="""The memory profiles.""" + ) + profiles: Optional[dict[str, MemoryProfile]] = Field( + default=None, + description="""The retrieved structured profiles, which match the schemas under the requested scope. The key is the ID of the schema that the profile is linked with, which corresponds to the `schema_id` defined inside the `SchemaConfig`, under `StructuredMemoryCustomizationConfig`.""", + ) + + +class RetrieveProfilesResponseDict(TypedDict, total=False): + """The response for retrieving memory profiles.""" + + memory_profiles: Optional[dict[str, MemoryProfileDict]] + """The memory profiles.""" + + profiles: Optional[dict[str, MemoryProfileDict]] + """The retrieved structured profiles, which match the schemas under the requested scope. The key is the ID of the schema that the profile is linked with, which corresponds to the `schema_id` defined inside the `SchemaConfig`, under `StructuredMemoryCustomizationConfig`.""" + + +RetrieveProfilesResponseOrDict = Union[ + RetrieveProfilesResponse, RetrieveProfilesResponseDict +] + + class RollbackAgentEngineMemoryConfig(_common.BaseModel): """Config for rolling back a memory.""" @@ -10303,6 +10559,14 @@ class IntermediateExtractedMemory(_common.BaseModel): fact: Optional[str] = Field( default=None, description="""Output only. The fact of the extracted memory.""" ) + structured_data: Optional[dict[str, Any]] = Field( + default=None, + description="""Output only. Represents the structured value of the extracted memory.""", + ) + context: Optional[str] = Field( + default=None, + description="""Output only. Represents the explanation of why the information was extracted from the source content.""", + ) class IntermediateExtractedMemoryDict(TypedDict, total=False): @@ -10311,6 +10575,12 @@ class IntermediateExtractedMemoryDict(TypedDict, total=False): fact: Optional[str] """Output only. The fact of the extracted memory.""" + structured_data: Optional[dict[str, Any]] + """Output only. Represents the structured value of the extracted memory.""" + + context: Optional[str] + """Output only. Represents the explanation of why the information was extracted from the source content.""" + IntermediateExtractedMemoryOrDict = Union[ IntermediateExtractedMemory, IntermediateExtractedMemoryDict @@ -10344,6 +10614,10 @@ class MemoryRevision(_common.BaseModel): default=None, description="""Identifier. The resource name of the Memory Revision. Format: `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}/revisions/{memory_revision}`""", ) + structured_data: Optional[dict[str, Any]] = Field( + default=None, + description="""Output only. Represents the structured value of the memory at the time of revision creation.""", + ) class MemoryRevisionDict(TypedDict, total=False): @@ -10367,6 +10641,9 @@ class MemoryRevisionDict(TypedDict, total=False): name: Optional[str] """Identifier. The resource name of the Memory Revision. Format: `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}/revisions/{memory_revision}`""" + structured_data: Optional[dict[str, Any]] + """Output only. Represents the structured value of the memory at the time of revision creation.""" + MemoryRevisionOrDict = Union[MemoryRevision, MemoryRevisionDict]