Almacenes y esquema

Esta página presenta las abstracciones del almacén principal y los controles de esquema utilizados por el SDK de memoria del agente de Oracle.

API de tienda

Semántica de escritura de tienda

Las escrituras de almacén mantienen una separación clara entre el texto que almacena una aplicación y la carga útil que utiliza el almacén para la recuperación. La mayoría de las aplicaciones pueden utilizar las API de nivel de memoria y de thread y permitir que el almacén prepare las filas de búsqueda que necesita para la recuperación de vectores, palabras clave o híbridos. Las API de almacén de nivel inferior muestran index_texts, index_text, embeddings y embedding para integraciones avanzadas que ya saben qué texto o vectores se deben utilizar para la recuperación.

Piense en cada escritura como dos piezas relacionadas:

• contents en add() y text en update() controlan el texto del registro almacenado devuelto por get(), list() y los resultados de búsqueda.
• index_texts en add() y index_text en update() controlan el texto escrito en las filas de recuperación del almacén. La búsqueda utiliza esas filas y, a continuación, devuelve los registros lógicos originales.

Si no se proporciona ninguna sustitución de búsqueda ni embebido explícito, el almacén utiliza el texto almacenado resuelto como texto de recuperación. El almacén fragmenta el texto no vacío cuando se configura la fragmentación. El texto vacío almacena el texto del registro, pero no proporciona texto de recuperación.

La siguiente tabla describe cómo se selecciona el texto de recuperación antes de considerar las cargas útiles de vectores explícitos.

Cargas útiles de recuperación a nivel de almacén

Entrada	añadir()	actualizar()
index_texts o index_text omitidos	Cada registro utiliza su valor contents resuelto para la recuperación.	Se utiliza un valor text de sustitución para la recuperación. Si también se omite text, las actualizaciones de solo incrustación reutilizan las filas de texto de recuperación existentes del registro.
Entrada de cadena index_texts o cadena index_text	La cadena sustituye el texto de recuperación de ese registro. El almacén puede fragmentarlo antes de escribir filas de recuperación.	La cadena sustituye el texto de recuperación de ese registro. El almacén puede fragmentarlo antes de escribir filas de recuperación.
Entrada list[str] index_texts o list[str] index_text	La lista se trata como fragmentos propiedad de la persona que llama. Cada cadena que no está vacía se escribe como una fila de recuperación y el almacén no la fragmenta de nuevo.	La lista se trata como fragmentos propiedad de la persona que llama. Cada cadena que no está vacía se escribe como una fila de recuperación y el almacén no la fragmenta de nuevo.
Entrada None index_texts o index_text=None	None en la lista externa index_texts significa "usar el contenido almacenado para este registro".	index_text=None borra las filas de recuperación al dejar el texto almacenado sin cambios, a menos que también se proporcione text.
Cadena vacía o lista de fragmentos vacía	Almacena el texto del registro y no proporciona texto de recuperación para ese registro.	Actualiza el texto del registro cuando se proporciona text y borra el texto de recuperación para ese registro.

Las incrustaciones explícitas son opcionales. Cuando se omiten, el almacén deriva vectores locales del texto de recuperación cuando se configura el almacenamiento de vectores locales; los almacenes de palabras clave o híbridos también pueden utilizar filas de recuperación de solo texto. Cuando se proporcionan valores embeddings o embedding explícitos, el almacén escribe esos vectores directamente y no llama a su embebido para esos vectores.

En add(), embeddings=None se comporta como omitir embeddings. En update(), embedding=None es explícito: el almacén mantiene o reescribe el texto de recuperación según text y index_text, pero almacena esas filas sin vectores locales. Si se omiten text y index_text, se borrarán los vectores de las filas de recuperación existentes.

La forma del vector indica a la tienda cuánta propiedad del fragmento está tomando la persona que llama:

• Un vector significa un vector para todo el texto de recuperación. El almacén no divide ese texto para el vector explícito. Si el texto de recuperación está vacío, el vector se puede almacenar sin texto de fragmento complementario.
• varios vectores significan un vector por fragmento propiedad de la persona que llama. Proporcione listas de fragmentos index_texts o index_text coincidentes, o bien utilice un update() de solo embebido que reutilice las filas de texto de recuperación existentes del registro.
• los recuentos de vectores deben coincidir con los recuentos de fragmentos y todos los vectores explícitos de una llamada add() deben tener la misma dimensión.
• solo se permite una carga útil de vector vacía por registro cuando no hay filas de texto de recuperación que alineen con ella.

Algunas combinaciones se rechazan para que el texto almacenado, el texto de recuperación y los vectores no se desvíen. Al transferir text=None, se borran el texto almacenado y las filas de recuperación, por lo que no se puede combinar con valores index_text o embedding no nulos; los registros de perfil de actor no soportan text=None. La transferencia de index_text=None en update() significa "borrar filas de recuperación", por lo que no se permiten incrustaciones explícitas no vacías en la misma llamada. Varios vectores explícitos necesitan texto de fragmento explícito, a menos que la actualización sea de solo embebido y las filas de recuperación existentes ya proporcionen el texto de fragmento.

clase oracleagentmemory.core.OracleMemoryStore

Bases: IMemoryStore

Interfaz de almacén común utilizada por OracleAgentMemory.

La implantación de un almacén es responsable de mantener los registros de texto y realizar una búsqueda de similitud sobre ellos. Tanto los puntos de entrada síncronos como los asíncronos se definen para que las API de nivel superior puedan exponer las superficies de sincronización/asíncronas coincidentes sin duplicar la lógica específica del almacén.

método add

Agregue registros a la tienda.

• Parámetros:
  • contents list[str | None]: registra las cargas útiles para que se mantengan. Los valores de texto también se utilizan para la indexación semántica a menos que se proporcionen index_texts o embeddings. Cuando un valor de texto es None, las implantaciones pueden volver a ser metadata["content"]. Las cadenas vacías explícitas se conservan.
  • record_type str: tipo de registro lógico para crear, por ejemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • index_texts list[str | list[str] | None]: cargas útiles alternativas opcionales que se utilizan solo para la indexación semántica. Cuando se proporciona, la lista externa debe alinearse con las entradas de texto. Cada entrada puede ser una cadena, que la tienda puede fragmentar internamente, o una lista de cadenas no vacías, que la tienda trata como fragmentos propiedad de la persona que llama y no debe dividirse de nuevo.
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]: vectores de incrustación precalculados opcionales alineados con las entradas de texto. Cada entrada de registro puede ser un vector de incrustación o una lista de vectores de incrustación de fragmentos para ese registro. Cuando se proporciona, la tienda debe utilizar estos vectores directamente en lugar de llamar a su embebedor. Para varios vectores de un registro es necesario que coincidan con las listas de fragmentos index_texts para que los límites de fragmentos de texto y vector sean explícitos. Si no se proporciona, los almacenes suelen derivar el estado semántico de su embebido configurado, pero los modos de indexación adaptados al texto específicos de la implantación también pueden permitir escrituras de solo texto sin uno.
  • record_ids str | None | list[str | None]: identificadores visibles para el emisor de llamada opcionales. Se puede utilizar una sola cadena para inserciones de un solo registro, mientras que las listas deben alinearse con las entradas de texto. Los identificadores generados se devuelven cuando se omite este campo.
  • thread_ids str | None | list[str | None]: identificadores de subprocesos opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • user_ids str | None | list[str | None]: identificadores de usuario opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • agent_ids str | None | list[str | None]: identificadores de agente opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • roles str | None | list[str | None]: roles de mensajes opcionales, como "user" o "assistant". Los valores escalares se pueden difundir entre entradas de texto alineadas. Se utiliza solo si record_type es "message".
  • timestamps str | None | list[str | None]: registros de hora opcionales para guardar con los registros. Cada registro de hora representa el momento en que se creó el registro. Los valores escalares se pueden difundir entre entradas de texto alineadas. Las entradas omitidas o None utilizan la hora actual.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: diccionarios de metadatos opcionales proporcionados por el emisor de llamada. Los metadatos pueden incluir "content" como origen de reserva cuando se omite un valor de texto en lugar de definirse explícitamente en "".
  • ttl_days int | None | list[int | None]: duración opcional del tiempo de vida en días para los registros que admiten la caducidad. Omita este argumento para utilizar el valor por defecto del almacén. Transfiera None para los registros que no deben caducar. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para que caduque en relación con el tiempo de creación almacenado o TimeToLiveAnchor.TIMESTAMP para que caduque en relación con el registro de hora de evento de cada registro. Cuando se omite, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Tipo de devolución: list[str]

Notas

Utilice add_batches() cuando el emisor de llamada ya tenga uno o más objetos PendingRecordBatch.

• Devoluciones: identificadores para los registros insertados, en el mismo orden lógico que la entrada.
• Tipo de devolución: List[str]
• Parámetros:
  • contenido list[str | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any

method add_agent (resumen)

Agregue un registro de perfil de agente.

• Parámetros:
  • agent_id str: identificador estable para el perfil de agente.
  • information str: texto de formato libre que describe el agente.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente creado.
• Tipo de devolución: str

method add_async (async)

Agregar de forma asíncrona registros orientados a filas al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add().

• Parámetros:
  • contenido list[str | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_batches

Agregue lotes lógicos preparados por el emisor de llamada al almacén.

• Parámetros:
  • lotes list[PendingRecordBatch]: lotes lógicos completamente preparados para que persistan. Cada lote debe incluir sus propios campos por registro, como record_type, valores de ámbito, roles, registros de hora y metadatos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Devoluciones: identificadores de los registros insertados, en el mismo orden lógico que los lotes y las filas de entrada.
• Tipo de devolución: List[str]

Ejemplos

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (async)

Agregue lotes lógicos preparados por el emisor de llamada de forma asíncrona al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add_batches().

• Parámetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de devolución: list[str]

method add_user (resumen)

Agregue un registro de perfil de usuario.

• Parámetros:
  • user_id str: identificador estable para el perfil de usuario.
  • information str: texto de formato libre que describe al usuario.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario creado.
• Tipo de devolución: str

method delete (resumen)

Elimine un registro almacenado por identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe eliminar.
  • record_id str: identificador del registro que se debe eliminar.
  • cascade bool: cuando es True, aplique cualquier comportamiento de supresión en cascada admitido por el almacén para los destinos de nivel superior solicitados dentro de la misma operación de supresión. Esto se utiliza principalmente para destinos como los perfiles de actor que poseen registros de ámbito adicionales. Por ejemplo, una cascada de perfil de usuario o perfil de agente puede suprimir los propios threads, los mensajes de ámbito de thread y los registros similares a la memoria eliminados con esos threads, así como cualquier registro de ámbito de actor directo restante, como mensajes, memorias, directrices, hechos o preferencias. Para las supresiones de perfil de actor, esta limpieza de ámbito puede seguir ejecutándose cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de registros de nivel superior solicitados suprimidos, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

method delete_thread (resumen)

Suprimir un thread y sus datos almacenados asociados.

• Parámetros: thread_id str: identificador del subproceso que se va a eliminar.
• Devoluciones: número de registros de thread suprimidos, normalmente 0 o 1.
• Tipo de devolución: int

Notas

Ésta es la operación de nivel de almacén para eliminar un thread y los registros de ámbito de thread gestionados por el almacén. Prefiere la supresión de threads cuando los requisitos de retención llaman para suprimir tanto los mensajes de origen como los datos de memoria de ámbito de thread derivados, ya que las supresiones de nivel de mensaje no implican que se eliminen registros derivados persistentes por separado.

method get (resumen)

Recupere un registro almacenado por tipo e identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe recuperar.
  • record_id str: identificador del registro que se recuperará.
• Devoluciones: el registro almacenado cuando se encuentra; de lo contrario, None.
• Tipo de devolución: Registro | Ninguno

method list (resumen)

Mostrar registros almacenados para un tipo de registro.

• Parámetros:
  • record_type str: tipo de registro lógico que se debe enumerar.
  • limit int | None: número máximo opcional de registros más recientes que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor thread_id es None. Los tipos de registro sin ámbito ignoran este filtro.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor user_id es None. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor agent_id es None. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyos metadatos son None. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

• Devoluciones: registros ordenados de más antiguos a más recientes en la ventana devuelta.
• Tipo de devolución: List[Registro]

method list_thread_messages (resumen)

Mostrar el historial de mensajes almacenado para un thread.

• Parámetros:
  • thread_id str: identificador del thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben incluir. Cuando se omite, se devuelven todos los mensajes almacenados para el thread.
• Devoluciones: registros de mensajes ordenados de más antiguo a más reciente dentro de la ventana devuelta.
• Tipo de devolución: List[MessageRecord]

method search (resumen)

Buscar registros por similitud.

• Parámetros:
  • query str | None: consulta en lenguaje natural. Se debe proporcionar cuando se omite query_vector.
  • query_vector list[float] | None: incrustación opcional de consultas calculadas previamente. Se debe proporcionar exactamente uno de query y query_vector.
  • k int: número máximo de resultados que se deben devolver. Los valores explícitos deben ser al menos 1. Este es un límite superior: la llamada puede devolver menos de k resultados cuando los filtros son demasiado restrictivos, cuando existen menos registros coincidentes no vencidos o debido al comportamiento de búsqueda específico de la implementación.
  • thread_id str | None: ámbito de subproceso opcional.
  • user_id str | None: filtros de ámbito de agente y usuario opcionales.
  • agent_id str | None: filtros de ámbito de agente y usuario opcionales.
  • exact_user_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • exact_agent_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • exact_thread_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • record_types set[str] | None: conjunto opcional de tipos de registro que se deben incluir.
  • metadata_filter dict[str, Any] | None: asignación de filtros de metadatos opcional. Las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz.
• Devoluciones: pares (record, distance) ordenados por distancia creciente. La lista puede contener menos de k entradas.
• Tipo de devolución: list[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

Ejemplos

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

Filtrar en un valor de metadatos escalar:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtrar por metadatos anidados:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Hacer coincidir un valor de lista exactamente, incluido el orden:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtrar cuando una matriz de metadatos contiene un valor:

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Combinar varias condiciones de metadatos. Un registro debe satisfacer todas las claves:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method search_async (async)

Busque registros de forma asíncrona por similitud semántica.

• Parámetros:
  • query str | None: el mismo texto de consulta aceptado por search.
  • k int: el mismo recuento máximo de resultados aceptado por search. Los valores explícitos deben ser al menos 1.
  • query_vector list[float] | None: la misma incrustación opcional de consulta calculada previamente aceptada por search.
  • thread_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • user_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • agent_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • exact_user_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_agent_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_thread_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • record_types set[str] | None: el mismo filtro de tipo de registro opcional aceptado por search.
  • metadata_filter dict[str, Any] | None: el mismo filtro de metadatos opcional aceptado por search, incluidos escalar, anidado, lista exacta, pertenencia a una matriz y condiciones combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} y {"tags": {"$array_contains": "prod"}}.
• Devoluciones: pares (record, distance) devueltos por la llamada search subyacente.
• Tipo de devolución: List[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

method update (resumen)

Actualizar el contenido del registro almacenado, incrustar datos, metadatos, registro de hora o caducidad.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe actualizar.
  • record_id str: identificador del registro que se debe actualizar.
  • text str | None: contenido de sustitución opcional. Transfiera None para borrar explícitamente el texto almacenado cuando el almacén lo soporte. Las tiendas también pueden borrar el estado semántico asociado y rechazar las actualizaciones index_text o embedding no nulas en conflicto en la misma llamada. Omita el argumento para dejar el contenido sin cambios.
  • index_text str | list[str] | None: carga útil semántica alternativa opcional que se utiliza para volver a calcular o reemplazar el estado de búsqueda almacenado sin cambiar el texto persistente. Una cadena puede ser fragmentada internamente por la tienda. Una lista de cadenas no vacías se trata como fragmentos propiedad del emisor de llamada y no se debe volver a dividir. Algunas implementaciones también pueden persistir esto por separado como texto de búsqueda híbrida.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None: vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Varios vectores necesitan listas de fragmentos index_text coincidentes o filas de texto de fragmento almacenadas existentes. Transfiera None para borrar explícitamente la embebida almacenada cuando el almacén la admita. Las tiendas con indexación adaptada al texto también pueden permitir actualizaciones semánticas sin embeber ni embeber explícitamente.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Transfiera None para borrar los metadatos cuando el almacén los soporte.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Omita este argumento para dejar el registro de hora almacenado sin cambios. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se agregó a la tienda cuando la tienda lo admite.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para borrar la caducidad.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación del registro o TimeToLiveAnchor.TIMESTAMP para la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Si se proporciona ttl_anchor sin ttl_days, se utiliza la duración de tiempo de actividad por defecto del almacén o esquema. Cuando se omite ttl_anchor durante un refrescamiento, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
• Devoluciones: número de registros actualizados, normalmente 0 o 1. Devuelve 0 cuando ningún registro almacenado coincide con el identificador lógico solicitado.
• Tipo de devolución: int
• Incidencias: ValueError: si la carga útil de actualización no es válida para el almacén, como omitir todos los campos opcionales o proporcionar argumentos semánticos en conflicto.

Almacén de Oracle DB

clase oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Persistencia respaldada por base de datos para mensajes, memorias y perfiles de actores.

Cree un almacén de Oracle DB.

• Parámetros:
  • embedder IEmbedder | None: embebido que se utiliza cuando el almacén necesita incrustaciones de vectores locales. Puede ser None cuando los emisores de llamadas siempre proporcionan vectores previamente calculados o cuando se utiliza la búsqueda por palabras clave con escrituras de solo texto y consultas de texto. SearchStrategy.HYBRID necesita OracleDBEmbedder aquí para que el índice híbrido gestionado pueda utilizar el modelo de base de datos de este embebido.
  • pool Any: conexión o pool de Oracle DB. La transferencia de una conexión raw permite el modo de sesión única para esta instancia de almacén: las llamadas de almacén simultáneas se serializan localmente para conservar las suposiciones de bloqueo de filas y transacción utilizadas por las operaciones de escritura. Utilizar un pool de conexiones para solicitudes simultáneas.
  • schema_policy: SchemaPolicy | str modo de configuración de esquema. El valor por defecto es que se necesita un esquema gestionado existente y actualizado y no se realizan cambios de DDL. Utilice SchemaPolicy.CREATE_IF_NECESSARY para rellenar los objetos que faltan o SchemaPolicy.RECREATE para borrar y volver a crear objetos gestionados. SchemaPolicy.CREATE_IF_NECESSARY puede aplicar actualizaciones de versión de esquema gestionadas soportadas, puede actualizar un esquema vectorial para la búsqueda por palabras clave agregando un índice de texto o para la búsqueda híbrida agregando las estructuras de búsqueda gestionadas y el índice híbrido.
  • vector_dim int | None: dimensión de incrustación opcional para el almacenamiento de vectores local. Transfiera un entero positivo para crear la columna de embebido gestionada y el índice de vector, y para validar los metadatos de esquema existentes con esa dimensión. Transfiera None u omita el argumento cuando este almacén no necesite almacenamiento de vectores local. La búsqueda híbrida y por palabras clave puede funcionar desde el texto de búsqueda almacenado sin la columna de incrustación local. La búsqueda de vectores requiere almacenamiento de vectores local.

  • table_name_prefix str:

    Prefijo opcional agregado a los nombres de tabla/índice gestionados. Pase esto o memory_store_id, no ambos.

    Nota: En desuso desde la versión 26.6.0: este parámetro estaba en desuso en la versión 26.6.0 y se eliminará en la versión 27.1. Utilice memory_store_id en su lugar.

  • memory_store_id str: ID estable para el almacén de memoria de base de datos gestionado. Vuelva a utilizar el mismo ID para volver a abrir la misma tienda gestionada. El ID se une a los nombres de objetos de base de datos gestionados con un guion bajo, por lo que debe empezar por una letra, contener solo letras, números y guiones bajos y tener como máximo 16 caracteres. Pase esto o table_name_prefix, no ambos. Si se omite, el almacén utiliza table_name_prefix o el valor por defecto sin fijar cuando también se omite table_name_prefix.
  • search_strategy SearchStrategy: valor SearchStrategy que selecciona el backend para search(). Utilice SearchStrategy.VECTOR (valor por defecto) para la recuperación sólo vectorial, SearchStrategy.HYBRID para consultar un índice vectorial híbrido de Oracle gestionado a través del texto de búsqueda almacenado, o SearchStrategy.KEYWORD para clasificar por palabra clave/texto que coincida con el texto de búsqueda almacenado sin fusión vectorial. KEYWORD no necesita un embebido. HYBRID necesita que embedder sea OracleDBEmbedder para que el índice híbrido gestionado utilice el mismo modelo en la base de datos que el embebido del almacén principal. Si un cliente de palabras clave abre un esquema híbrido existente, el almacén puede utilizar la rama de texto de ese índice híbrido. El inicio falla cuando se utiliza una estrategia incompatible con un esquema existente porque puede que ese esquema no contenga el estado de búsqueda almacenado que necesita la estrategia.
  • search_index_sync SearchIndexSyncMode: valor SearchIndexSyncMode que selecciona el comportamiento de refrescamiento del índice de búsqueda gestionado para SearchStrategy.HYBRID y SearchStrategy.KEYWORD. SearchIndexSyncMode.ON_COMMIT es el valor por defecto y permite la búsqueda de registros tan pronto como se confirma la transacción de escritura. SearchIndexSyncMode.MANUAL deja el refrescamiento en una operación de sincronización explícita del lado de la base de datos. SearchIndexSyncMode.AUTO permite a Oracle refrescar el índice híbrido gestionado de forma asíncrona y solo está soportado con SearchStrategy.HYBRID; la búsqueda por palabra clave rechaza AUTO.
  • memory_retention_config MemoryRetentionConfig: configuración opcional de retención de memoria para mensajes y memorias respaldados por base de datos. MemoryRetentionConfig.default_ttl_days se utiliza cuando una nueva escritura omite ttl_days. MemoryRetentionConfig.max_ttl_days sujeta duraciones explícitas por registro por encima del máximo configurado con una advertencia y, cuando se define, hace que ttl_days=None utilice ese máximo en lugar de crear filas que no caducan. Con SchemaPolicy.CREATE_IF_NECESSARY, una configuración explícita refresca los metadatos almacenados en un esquema gestionado actualizado existente, pero no actualiza las fechas de caducidad existentes; omitiendo la configuración existente. Si una configuración explícita deja default_ttl_days o max_ttl_days en NOT_SET_MARKER, el SDK resuelve ese atributo en su valor por defecto (None) antes de comparar o almacenar metadatos de esquema. Elija esta configuración en función de la información esperada que se almacena en los registros, el motivo por el que la aplicación la retiene y cualquier compromiso de conservación de aplicaciones o normativas.

Advertencia: SchemaPolicy.CREATE_IF_NECESSARY puede ser más caro que el inicio normal del almacén porque puede aplicar el DDL de esquema gestionado y las reescrituras de datos de mejor esfuerzo antes de que la inicialización se realice correctamente. Planifique la primera apertura de un esquema gestionado anterior como una operación de migración o mantenimiento cuando ese esquema pueda contener muchas filas.

Si la configuración del esquema debe crear el trabajo de depuración de registro caducado gestionado, pero el usuario de la base de datos carece del privilegio Scheduler-job, la inicialización advierte y continúa. Los mensajes y las memorias caducados permanecen ocultos para las lecturas y la búsqueda, pero no se depuran físicamente hasta que un usuario con CREATE JOB o un privilegio de programador equivalente crea el trabajo.

Cuando SchemaPolicy.CREATE_IF_NECESSARY crea por primera vez un índice híbrido gestionado a través de un esquema existente, Oracle explora el texto de búsqueda almacenado y crea el estado de índice híbrido gestionado a partir del modelo de base de datos configurado. La inicialización del almacén espera a que termine ese DDL, por lo que debe planificar la primera actualización híbrida como una operación de migración o mantenimiento para esquemas grandes. SearchIndexSyncMode controla el mantenimiento continuo después de que exista el índice; no hace que la primera creación de índice sea asíncrona.

La creación de ese índice híbrido gestionado también crea una preferencia de vectorizador DBMS_VECTOR_CHAIN denominada por el esquema gestionado. La preferencia almacena metadatos de configuración del vectorizador ligeros del modelo OracleDBEmbedder configurado. Se puede inspeccionar con vistas de preferencias de Oracle Text, como CTX_USER_PREFERENCES y CTX_USER_PREFERENCE_VALUES.

método add

Agregue registros al almacén de Oracle DB.

• Parámetros:
  • contents list[str | None]: registra las cargas útiles para que se mantengan. Los valores de texto también se utilizan para el texto de búsqueda a menos que se proporcione index_texts. Cuando un valor de texto es None, el almacén puede volver a metadata["content"]. Las cadenas vacías explícitas se conservan.
  • record_type str: tipo de registro lógico que se debe crear, como "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • index_texts list[str | list[str] | None]: cargas útiles alternativas opcionales utilizadas como texto de búsqueda. Utilice esta opción para controlar qué palabras clave respaldadas por base de datos o índices de búsqueda híbridos. Cada entrada de la lista externa se alinea con un registro. La tienda puede fragmentar una entrada de cadena. Una entrada de lista se trata como fragmentos propiedad del emisor de llamada y se escribe como está en RECORD_CHUNKS.chunk_text. Cuando también se proporciona embeddings, las entradas de lista requieren exactamente un vector por fragmento; las entradas de cadena solo aceptan un único vector para ese registro.

  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]:

    Vectores de incrustación precalculados opcionales alineados con contents. Cada entrada de registro puede ser un vector o una lista de vectores de fragmentos. Cuando se configura el almacenamiento vectorial local, estos vectores se almacenan directamente como representación vectorial del registro en lugar de llamar al incrustador de la tienda para crear vectores locales para la escritura. Un solo vector representa todo el texto semántico, incluso cuando el fragmentador configurado lo dividiría. Varios vectores de fragmentos necesitan que coincidan con las listas de fragmentos index_texts.

    En SearchStrategy.VECTOR, la búsqueda vectorial se clasifica en función de los vectores almacenados. En SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la búsqueda respaldada por base de datos clasifica en el texto de búsqueda almacenado y el estado de índice híbrido o texto gestionado por Oracle, por lo que las incrustaciones de tiempo de adición solo afectan a cualquier almacenamiento vectorial local configurado, no a esa estrategia de búsqueda activa. Si este almacén se ha configurado sin almacenamiento de vectores local, proporcione index_texts en lugar de embeddings para sustituir el texto visible para esos índices conscientes del texto.

  • record_ids str | None | list[str | None]: identificadores visibles para el emisor de llamada opcionales. Se puede utilizar una sola cadena para inserciones de un solo registro, mientras que las listas deben estar alineadas con contents. Los identificadores generados se devuelven cuando se omite este campo.
  • thread_ids str | None | list[str | None]: identificadores de subprocesos opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas.
  • user_ids str | None | list[str | None]: identificadores de usuario opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas.
  • agent_ids str | None | list[str | None]: identificadores de agente opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas.
  • roles str | None | list[str | None]: roles de mensajes opcionales, como "user" o "assistant". Se utiliza solo cuando record_type es "message".
  • timestamps str | None | list[str | None]: registros de hora opcionales para guardar con los registros. Cada registro de hora representa el momento en que se creó el registro. Los valores escalares se pueden difundir entre entradas alineadas. Las entradas omitidas o None dejan el registro de hora del evento sin definir. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, todos los registros afectados deben tener un valor de registro de hora ISO-8601 concreto. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: diccionarios de metadatos opcionales. Los metadatos pueden incluir "content" como origen de reserva cuando se omite un valor de texto en lugar de definirlo en "".
  • ttl_days int | None | list[int | None]: duración opcional del tiempo de vida en días para registros similares a los de la memoria y los mensajes. Omita este argumento para utilizar MemoryRetentionConfig.default_ttl_days desde el esquema gestionado. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para crear un registro que no caduque cuando no lo haga. Los valores por encima de MemoryRetentionConfig.max_ttl_days se sujetan a ese máximo con una advertencia. Los valores escalares se pueden difundir entre entradas alineadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para que caduque en relación con el tiempo de creación de la base de datos o TimeToLiveAnchor.TIMESTAMP para que caduque en relación con el registro de hora del evento proporcionado. Cuando se omite, la caducidad utiliza TimeToLiveAnchor.CREATED_AT. La caducidad anclada en el registro de hora requiere un registro de hora ISO-8601 concreto para cada registro insertado. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • **store_kwargs (Cualquiera): opciones de escritura de base de datos. batch_size controla el tamaño de lote de ejecución y el valor por defecto es 256.
• Devoluciones: identificadores para los registros insertados, en el mismo orden lógico que la entrada.
• Tipo de devolución: list[str]

Ejemplos

store.add(
    ["Index this stored text"],
    record_type="memory",
    record_ids="mem-db-add-docs",
)
['mem-db-add-docs']
store.add(
    ["Stored text"],
    record_type="memory",
    index_texts=["Search this text"],
    record_ids="mem-db-index-text-docs",
)
['mem-db-index-text-docs']
store.add(
    ["Short-lived event"],
    record_type="memory",
    record_ids="mem-db-ttl-docs",
    timestamps="2026-01-01T12:00:00+00:00",
    ttl_days=7,
    ttl_anchor=TimeToLiveAnchor.TIMESTAMP,
)
['mem-db-ttl-docs']

método add_agent

Agregue un registro de perfil de agente.

• Parámetros:
  • agent_id str: identificador de agente.
  • information str: información de formato libre sobre el agente. Este texto se almacena como contenido del perfil y se utiliza para crear la representación que permite la búsqueda del perfil.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente insertado.
• Tipo de devolución: str

Notas

Los registros de perfil de agente no tienen ámbito. El identificador de registro público insertado es el mismo valor transferido que agent_id.

Ejemplos

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

method add_async (async)

Agregar de forma asíncrona registros orientados a filas al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add().

• Parámetros:
  • contenido list[str | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_batches

Agregue lotes lógicos preparados por el emisor de llamada al almacén.

• Parámetros:
  • lotes list[PendingRecordBatch]: lotes lógicos completamente preparados para que persistan. Cada lote debe incluir sus propios campos por registro, como record_type, valores de ámbito, roles, registros de hora y metadatos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Devoluciones: identificadores de los registros insertados, en el mismo orden lógico que los lotes y las filas de entrada.
• Tipo de devolución: List[str]

Ejemplos

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (async)

Agregue lotes lógicos preparados por el emisor de llamada de forma asíncrona al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add_batches().

• Parámetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_user

Agregue un registro de perfil de usuario.

• Parámetros:
  • user_id str: identificador de usuario.
  • information str: información de formato libre sobre el usuario. Este texto se almacena como contenido del perfil y se utiliza para crear la representación que permite la búsqueda del perfil.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario insertado.
• Tipo de devolución: str

Notas

Los registros de perfil de usuario no tienen ámbito. El identificador de registro público insertado es el mismo valor transferido que user_id.

Ejemplos

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

método delete

Suprima una fila gestionada y sus filas de fragmentos por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro para eliminar. Los tipos soportados son "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" y "agent_profile".
  • record_id str: identificador para suprimir.
  • cascade bool: cuando es True, amplíe los destinos de nivel superior soportados, como los perfiles de actor, a sus filas secundarias de ámbito dentro de la misma transacción. Para un destino de perfil de usuario o de perfil de agente, primero se suprimen las filas de thread en propiedad, lo que elimina su mensaje de ámbito de thread y las filas de la tabla de memoria y, a continuación, se suprimen los mensajes de ámbito de actor y las filas similares a la memoria restantes directamente (memory, guideline, fact, preference). Esta limpieza de ámbito se sigue ejecutando cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de destinos de nivel superior solicitados eliminados, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

Notas

La operación se ejecuta dentro de una transacción. Cuando cascade está activado para un destino de nivel superior soportado, la supresión de perfil y todas las supresiones secundarias de ámbito se confirman o se realiza un rollback juntos.

Ejemplos

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

método delete_thread

Suprimir un thread y sus filas almacenadas asociadas.

• Parámetros: thread_id str: identificador de thread cuyas filas se deben eliminar, incluida la fila de thread, las filas secundarias dependientes y la limpieza explícita de la fila de fragmento.
• Devoluciones: número de filas de thread suprimidas (0 o 1).
• Tipo de devolución: int

Notas

Utilice esta operación cuando necesite una limpieza en cascada con ámbito de thread. En el almacén con copia de seguridad de base de datos, al suprimir el thread, se elimina la fila del thread gestionado junto con las filas de memoria y mensajes asociadas, además de los datos de búsqueda mantenidos para su recuperación. Esto es más amplio que una supresión de nivel de mensaje, que elimina sólo la fila de mensaje sin formato. La supresión de threads elimina las filas de memoria y mensajes dependientes junto con sus datos de recuperación asociados en la misma transacción.

Ejemplos

store.delete_thread("c1")
0

método get

Recuperar un registro almacenado por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro que se resuelve en una fila gestionada, como "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • record_id str: identificador que se debe buscar.
• Devoluciones: registro rellenado con metadatos descodificados cuando se encuentra, de lo contrario, None.
• Tipo de devolución: Registro | Ninguno

Ejemplos

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

method list

Enumerar registros persistentes para un tipo de registro.

• Parámetros:
  • record_type str: etiqueta de tipo de registro (por ejemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile").
  • limit int | None: número máximo opcional de registros que se deben devolver. Cuando se omite, el almacén utiliza su límite de lista por defecto. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor thread_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor user_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor agent_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros sin metadatos almacenados. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

• Devoluciones: registros ordenados por orden de inserción.
• Tipo de devolución: list[Registro]

Notas

"user_profile" y "agent_profile" son tipos de registro sin ámbito. Para esos tipos de registro, thread_id, user_id y agent_id se ignoran y la identidad del actor permanece en record.id.

Ejemplos

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

método list_thread_messages

Devolver mensajes persistentes para un hilo.

• Parámetros:
  • thread_id str: identificador de thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben devolver.
• Devoluciones: registros de mensajes ordenados por orden de inserción.
• Tipo de devolución: list[MessageRecord]

Ejemplos

store.list_thread_messages("c1")
[]

método search

Buscar registros por similitud.

El backend de búsqueda activo depende del SearchStrategy configurado en el almacén. SearchStrategy.VECTOR clasifica el vector de consulta en vectores de registro almacenados. SearchStrategy.HYBRID consulta el índice híbrido gestionado de Oracle a través del texto de búsqueda almacenado y su estado de índice gestionado. SearchStrategy.KEYWORD solo se clasifica por texto que coincida con el texto de búsqueda almacenado.

• Parámetros:
  • query str | None: texto opcional en lenguaje natural que se utiliza para buscar registros coincidentes o similares. Proporcione al menos un carácter no de espacio en blanco cuando se omite query_vector. La búsqueda vectorial incrusta este texto; la búsqueda por palabras clave lo compara con el texto de búsqueda almacenado; la búsqueda híbrida lo utiliza tanto para la recuperación de texto como de vector.
  • query_vector list[float] | None: incrustación opcional de consultas calculadas previamente. Se debe proporcionar exactamente uno de query y query_vector. En la búsqueda vectorial, esto se compara con los vectores de registro almacenados. En la búsqueda híbrida, se envía al índice híbrido gestionado de Oracle como entrada de vector del lado de consulta y no hace que el almacén de base de datos se compare con vectores almacenados de tiempo adicional o de tiempo de actualización directamente. La búsqueda por palabra clave no acepta query_vector. El vector debe ser no vacío, unidimensional y contener solo valores numéricos finitos. En la búsqueda híbrida, su dimensión debe coincidir con el modelo OracleDBEmbedder configurado.
  • k int: número máximo de resultados que se deben devolver. Los valores explícitos deben ser al menos 1. Este es un límite superior: la llamada puede devolver menos de k resultados cuando los filtros son demasiado restrictivos, cuando existen menos registros coincidentes no vencidos o debido al comportamiento de búsqueda específico de la implementación.
  • thread_id str | None: identificador de ámbito de thread opcional. exact_thread_match=False deja la dimensión de thread sin restricciones. exact_thread_match=True coincide exactamente con el thread_id proporcionado. Si thread_id=None, solo coincide con los registros sin ámbito en la dimensión de thread.
  • user_id str | None: identificadores opcionales de ámbito de agente y usuario. El indicador exact_*_match=False correspondiente deja esa dimensión sin restricciones. exact_*_match=True coincide exactamente con el ID proporcionado. Si el ID es None, solo coincide con los registros sin ámbito en esa dimensión.
  • agent_id str | None: identificadores de ámbito de agente y usuario opcionales. El indicador exact_*_match=False correspondiente deja esa dimensión sin restricciones. exact_*_match=True coincide exactamente con el ID proporcionado. Si el ID es None, solo coincide con los registros sin ámbito en esa dimensión.
  • exact_user_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • exact_agent_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • exact_thread_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • record_types set[str] | None: conjunto opcional de tipos de registro que se pueden buscar para incluir. Cuando se omite, la búsqueda de la base de datos abarca mensajes, filas de la tabla de memoria y perfiles de actor. Los perfiles de actor contribuyen con su carga útil information, mientras que las filas de mensaje y memoria contribuyen con su carga útil content. Durante la búsqueda, los tipos de registro de perfil utilizan su identificador de actor para la dimensión de ámbito aplicable mientras que las dimensiones de ámbito restantes se comportan como None.
  • metadata_filter dict[str, Any] | None: asignación de filtros de metadatos opcional. Las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz.
• Devoluciones: pares (record, distance) ordenados por distancia creciente. La lista puede contener menos de k entradas.
• Tipo de devolución: list[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1, si se proporcionan ambos o ninguno de los valores query y query_vector, si query está en blanco, si el modo vectorial no puede resolver una incrustación de consulta, si query_vector no es válido o si metadata_filter no es válido.

Ejemplos

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

Filtrar en un valor de metadatos escalar:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtrar por metadatos anidados:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Hacer coincidir un valor de lista exactamente, incluido el orden:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtrar cuando una matriz de metadatos contiene un valor:

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Combinar varias condiciones de metadatos. Un registro debe satisfacer todas las claves:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

method search_async (async)

Busque registros de forma asíncrona por similitud semántica.

• Parámetros:
  • query str | None: el mismo texto de consulta aceptado por search.
  • k int: el mismo recuento máximo de resultados aceptado por search. Los valores explícitos deben ser al menos 1.
  • query_vector list[float] | None: la misma incrustación opcional de consulta calculada previamente aceptada por search.
  • thread_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • user_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • agent_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • exact_user_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_agent_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_thread_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • record_types set[str] | None: el mismo filtro de tipo de registro opcional aceptado por search.
  • metadata_filter dict[str, Any] | None: el mismo filtro de metadatos opcional aceptado por search, incluidos escalar, anidado, lista exacta, pertenencia a una matriz y condiciones combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} y {"tags": {"$array_contains": "prod"}}.
• Devoluciones: pares (record, distance) devueltos por la llamada search subyacente.
• Tipo de devolución: List[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

método update

Actualizar contenido de registro almacenado, estado de búsqueda, metadatos y valores de registro de hora.

• Parámetros:
  • record_type str: etiqueta de tipo de registro de la fila que se está modificando (por ejemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile")
  • record_id str: identificador de la fila almacenada que se actualizará.
  • text str | None: el texto de sustitución opcional se mantiene en la columna content. Transfiera None para borrar el texto almacenado y borrar la incrustación almacenada. Transfiera solo argumentos semánticos None u omitidos en la misma llamada. Transfiera "" para conservar contenido vacío explícito al borrar cualquier representación vectorial almacenada para ese registro. Cuando se omite, el contenido existente no se modifica.
  • index_text str | list[str] | None: carga útil solo semántica opcional. Cuando se omite, text se utiliza para la indexación semántica. En los esquemas con capacidad híbrida, también se convierte en el texto de búsqueda almacenado que utiliza el componente de texto de Oracle. El almacén puede fragmentar un valor de cadena; un valor de lista se trata como fragmentos propiedad del emisor de llamada y se escribe como está en RECORD_CHUNKS. Cuando solo se proporciona embedding, el texto de búsqueda existente se vuelve a utilizar.

  • embedding list[float] | ndarray | list[list[float] | ndarray] | None:

    Vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se configura el almacenamiento vectorial local, se utiliza directamente y no se realiza ninguna llamada de incrustación. Transfiera None para borrar la embebida almacenada. Un único vector representa todo el texto de sustitución cuando se proporciona text, incluso cuando el fragmentador configurado dividiría ese texto. Se rechazan varios vectores de fragmentos al sustituir texto, a menos que index_text sea una lista de fragmentos. Cuando solo se proporciona embedding, el recuento de incrustaciones debe coincidir con las filas de fragmentos existentes del registro.

    En SearchStrategy.VECTOR, la búsqueda vectorial se clasifica en función de la incrustación almacenada. En SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la búsqueda respaldada por la base de datos clasifica en el texto de búsqueda almacenado y el estado de índice híbrido o texto gestionado por Oracle, por lo que las incrustaciones de tiempo de actualización solo afectan a cualquier almacenamiento vectorial local configurado, no a esa estrategia de búsqueda activa. Si este almacén se ha configurado sin almacenamiento vectorial local, proporcione index_text en lugar de embedding para actualizar el texto visible para esos índices conscientes del texto. Las actualizaciones semánticas de solo texto pueden omitir embedding por completo en esos modos.

  • metadata dict[str, Any] | None: asignación de metadatos opcional serializada a JSON y almacenada en metadata.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Cuando se omite, se conserva el registro de hora existente. Transfiera None para borrar el registro de hora guardado y utilice el tiempo de creación de la base de datos para futuros refrescamientos de caducidad de TimeToLiveAnchor.CREATED_AT. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para borrar la caducidad cuando no lo haga. Los valores por encima de MemoryRetentionConfig.max_ttl_days se sujetan a ese máximo con una advertencia. La actualización de la caducidad puede hacer que un registro caducado vuelva a estar visible si aún no se ha depurado.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para realizar un recuento a partir de la hora de creación almacenada, o TimeToLiveAnchor.TIMESTAMP para realizar un recuento a partir de la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Al proporcionar ttl_anchor sin ttl_days, se refresca la caducidad mediante MemoryRetentionConfig.default_ttl_days del esquema. Cuando se omite ttl_anchor durante un refrescamiento, el almacén utiliza TimeToLiveAnchor.CREATED_AT. Los refrescamientos con registro de hora anclados requieren un registro de hora ISO-8601 de sustitución en la misma llamada o un registro de hora de evento almacenado existente en ese formato. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
• Devoluciones: número de filas actualizadas (0 o 1). Devuelve 0 cuando ningún registro lógico coincide con record_type y record_id.
• Tipo de devolución: int
• Problemas: ValueError: si record_type no está soportado, si no se proporciona ninguna carga útil de actualización o si los argumentos de actualización semántica son incompatibles.

Ejemplos

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

Estrategia de búsqueda

clase oracleagentmemory.core.dbsearch.SearchStrategy

Bases: Enum

Comportamiento de búsqueda de almacenes de Oracle DB.

La inicialización del almacén de base de datos utiliza la estrategia seleccionada para seleccionar la capacidad de búsqueda de esquema gestionado. La búsqueda VECTOR almacena incrustaciones locales. La búsqueda KEYWORD almacena texto apto para búsqueda y un índice de texto. La búsqueda HYBRID almacena el texto que se puede buscar más el estado de índice vectorial híbrido gestionado por Oracle. El almacén de base de datos valida esta capacidad de esquema al iniciar para que una estrategia incompatible no devuelva resultados incompletos de forma silenciosa.

VECTOR

Buscar solo por similitud de vectores. La tienda embebebe la consulta con el embebido configurado o utiliza un query_vector proporcionado por el emisor de llamada y clasifica los registros por distancia de los vectores almacenados. Utilícelo con un esquema de base de datos configurado para la búsqueda vectorial.

HYBRID

Busque con el índice híbrido gestionado de Oracle. Oracle combina la coincidencia de texto sobre el texto de búsqueda almacenado con la clasificación vectorial del índice híbrido en la base de datos. Utilice esta opción cuando los usuarios puedan buscar por lenguaje natural, así como por identificadores exactos, alias o nombres de productos. Esta estrategia requiere que el embebido principal del almacén sea OracleDBEmbedder para que el índice gestionado y el almacén compartan un modelo en la base de datos.

KEYWORD

Busque solo por palabra clave/texto que coincida con el texto de búsqueda almacenado. Este modo no crea embebidas de consultas locales y no necesita un embebido de Oracle DB. Cuando se abre en un esquema híbrido existente, puede utilizar la rama de texto de ese índice híbrido sin crear un nuevo índice híbrido. Utilice esta opción cuando los identificadores exactos, los alias, los nombres de productos o las frases cortas deban permitir la recuperación de unidades sin fusión de vectores.

HYBRID = 'híbrido'

Palabra clave = 'palabra clave'

VECTOR = 'VECTOR'

Modo de sincronización de índice de búsqueda

clase oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Bases: Enum

Comportamiento de refrescamiento para índices de búsqueda de base de datos gestionados.

Este valor controla cuándo Oracle hace que el texto de búsqueda nuevo o cambiado sea visible para la búsqueda con reconocimiento de texto respaldada por base de datos. SearchStrategy.HYBRID utiliza el índice vectorial híbrido gestionado de Oracle. SearchStrategy.KEYWORD utiliza un índice de Oracle Text. SearchStrategy.VECTOR no utiliza este valor.

ON_COMMIT

Refresque el índice cuando se confirme la transacción de escritura. Esta es la opción por defecto y la más sencilla para la mayoría de las aplicaciones porque los registros se pueden buscar inmediatamente después de una escritura correcta. Puede agregar trabajo para escribir transacciones porque el índice se mantiene actualizado de inmediato.

MANUAL

No refresque el índice automáticamente. Es posible que los registros nuevos o actualizados no aparezcan en la búsqueda por palabra clave o híbrida hasta que ejecute la operación de sincronización de índice de la base de datos usted mismo. Esto resulta útil para cargas masivas o ventanas de mantenimiento en las que desea controlar cuando se ejecuta el trabajo de refrescamiento.

AUTO

Deje que Oracle refresque el índice híbrido gestionado de forma asíncrona. Las escrituras pueden evitar el costo de refrescamiento inmediato, pero los resultados de la búsqueda pueden retrasarse con respecto a las escrituras recientes hasta que Oracle complete el refrescamiento en segundo plano. Este modo solo está soportado con SearchStrategy.HYBRID.

Advertencia: este valor controla el mantenimiento continuo después de que exista el índice de búsqueda gestionado. No hace que la primera creación de índice sea asíncrona. La creación de un índice híbrido gestionado sobre el texto de búsqueda almacenado existente puede ser de larga ejecución porque Oracle crea el estado de índice híbrido gestionado a partir de ese texto.

AUTO = 'AUTO'

MANUAL = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

Periodo de vida

clase oracleagentmemory.core.retention.MemoryRetentionConfig

Bases: object

Configuración de retención de nivel de esquema para registros respaldados por Oracle DB.

• Parámetros:
  • default_ttl_days int | None: duración predeterminada del tiempo de vida, en días. Deje NOT_SET_MARKER para utilizar el valor por defecto de None (sin máximo).
  • max_ttl_days int | None: duración máxima opcional del tiempo de vida, en días. Deje NOT_SET_MARKER para utilizar el valor por defecto de None. Transfiera None sin máximo. Cuando se define, se trata de un límite estricto: las escrituras que intentan utilizar un valor ttl_days mayor se sujetan a este máximo con una advertencia y las API de escritura que pasan ttl_days=None utilizan este máximo en lugar de crear registros que no caducan.

clase oracleagentmemory.apis.ttl.TimeToLiveAnchor

Bases: Enum

Anclaje utilizado para calcular un registro de hora de caducidad a partir de una duración de tiempo de vida.

CREATED_AT

Caducidad de cálculo desde el registro de hora de creación de la base de datos del registro. Este es el valor por defecto cuando los emisores de llamadas omiten ttl_anchor.

TIMESTAMP

Calcular caducidad desde el registro de hora de evento almacenado del registro. Utilice esta opción cuando un mensaje o memoria represente un evento anterior y deba caducar en relación con la hora del evento en lugar de la hora de inserción.

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'TIMESTAMP' (Registro de hora)

Política de esquema

clase oracleagentmemory.core.SchemaPolicy

Bases: str, Enum

Política de creación de esquema para almacenes de Oracle DB.

REQUERIR_EXISTENTE

Valide que el esquema gestionado completo ya existe y que está actualizado. No cree ni modifique objetos de base de datos.

CREAR_IF_EMPTY

Si no existen objetos gestionados, esquema de inicialización de datos. Si ya existen objetos, necesita un esquema gestionado completo y actualizado.

CREAR_SI_NECESARIO

Cree los objetos gestionados que faltan y aplique actualizaciones de esquema gestionado soportadas.

VOLVER A CREAR

Borrar y volver a crear todos los objetos de esquema gestionados. Esto es destructivo.