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.

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

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_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 retorno: 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

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.