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

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 embeber, 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]: cargas útiles alternativas opcionales que se usan solo para incrustar/indexar. Cuando se proporciona, debe alinearse con las entradas de texto.
  • embeddings list[list[float]] | list[ndarray]: vectores de incrustación precalculados opcionales alineados con las entradas de texto. Cuando se proporciona, la tienda debe utilizar estos vectores directamente en lugar de llamar a su embebedor. Si no se proporciona, la tienda debe tener un embebedor adjunto; de lo contrario, se producirá un error.
  • 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 de eventos opcionales que se conservan con los registros. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | 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 "".
  • **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]
  • embeddings list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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.
• Devoluciones: identificador del registro de perfil de agente creado.
• Tipo de retorno: 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]
  • embeddings list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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.
• 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.
• 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.
  • thread_id str | None: ámbito de thread 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 metadatos parcial opcional. Un registro solo coincide cuando sus metadatos almacenados contienen todas las claves y valores solicitados. Los diccionarios anidados se comparan de forma recursiva. Los valores de lista coinciden con la igualdad exacta en lugar de la coincidencia de subjuegos recursivos, por lo que el orden y la longitud de la lista también deben coincidir.
• Devoluciones: pares (record, distance) ordenados por distancia creciente.
• 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

method search_async (async)

Buscar registros de forma asíncrona por similitud de vectores.

• 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.
• 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 o metadatos.

• 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 | None: carga útil de solo incrustación opcional que se utiliza para volver a calcular el vector almacenado sin cambiar el texto persistente.
  • embedding list[float] | ndarray | None: vector de incrustación precalculado opcional. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Transfiera None para borrar explícitamente la embebida almacenada cuando el almacén la admita.
  • 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.
• 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 utilizado para tipos de registro vectorizados. Puede ser None cuando los emisores de llamadas siempre proporcionan vectores previamente calculados en add, update y search.
  • 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. Utilice 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.
  • vector_dim int: dimensión de embebido para la creación de esquemas cuando se crean columnas VECTOR.
  • table_name_prefix str: prefijo opcional agregado a los nombres de tabla/índice gestionados.

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 embeber, 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]: cargas útiles alternativas opcionales que se usan solo para incrustar/indexar. Cuando se proporciona, debe alinearse con las entradas de texto.
  • embeddings list[list[float]] | list[ndarray]: vectores de incrustación precalculados opcionales alineados con las entradas de texto. Cuando se proporciona, la tienda debe utilizar estos vectores directamente en lugar de llamar a su embebedor. Si no se proporciona, la tienda debe tener un embebedor adjunto; de lo contrario, se producirá un error.
  • 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 de eventos opcionales que se conservan con los registros. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | 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 "".
  • **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]
  • embeddings list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any

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]
  • embeddings list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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_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 de perfil y se utiliza para crear la fila de embebido de perfil en RECORD_CHUNKS.
• 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'

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 de perfil y se utiliza para crear la fila de embebido de perfil en RECORD_CHUNKS.
• 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 mensaje asociadas, además de las filas del bloque de registro que se mantienen 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 mensaje dependientes a las que se hace referencia desde THREAD junto con las filas RECORD_CHUNKS coincidentes 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 dict, los metadatos almacenados deben contener todas las claves y valores solicitados. Los diccionarios anidados se comparan de forma recursiva. Los valores de lista coinciden con la igualdad exacta en lugar de la coincidencia de subjuegos recursivos, por lo que el orden y la longitud de la lista también deben coincidir.
• 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.

• 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.
  • 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 metadatos parcial opcional. Un registro solo coincide cuando sus metadatos almacenados contienen todas las claves y valores solicitados. Los diccionarios anidados se comparan de forma recursiva. Los valores de lista coinciden con la igualdad exacta en lugar de la coincidencia de subjuegos recursivos, por lo que el orden y la longitud de la lista también deben coincidir.
• Devoluciones: pares (record, distance) ordenados por distancia creciente.
• Tipo de devolución: list[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

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

method search_async (async)

Buscar registros de forma asíncrona por similitud de vectores.

• 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.
• 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

Actualice el contenido del registro almacenado, las incrustaciones de fragmentos y los valores de metadatos.

• 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 el contenido vacío explícito al borrar cualquier incrustación de fragmentos para ese registro. Cuando se omite, el contenido existente no se modifica.
  • index_text str | None: carga útil de solo incrustación opcional. Cuando se omite, text está embebido.
  • embedding list[float] | ndarray | None: vector de incrustación precalculado opcional. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Transfiera None para borrar la embebida almacenada.
  • metadata dict[str, Any] | None: asignación de metadatos opcional serializada a JSON y almacenada en metadata.
• 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'

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 solo los objetos gestionados que faltan, incluidos los metadatos.

VOLVER A CREAR

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