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 add (resumen)

Embeber y mantener registros de texto.

• Parámetros:
  • contents list[str | None]: cargas útiles de texto que se van a almacenar. Estos valores también se utilizan como cargas útiles de embebido cuando no se proporciona index_texts. Cuando se omite un elemento (None), los almacenes lo resuelven a partir de la clave de metadatos "content" cuando está disponible; de lo contrario, se mantiene el contenido vacío.
  • record_type str: etiqueta de tipo de registro para los registros almacenados (por ejemplo, "message" o "memory").
  • index_texts list[str]: cargas útiles de solo incrustación opcionales alineadas con contents.
  • embeddings list[list[float]] | list[ndarray]: vectores de incrustación precalculados opcionales alineados con contents. Cuando se proporciona, las tiendas utilizan estos vectores directamente y no llaman al grabador.
  • record_ids str | None | list[str] | list[None]: ID de registro visibles para el emisor de llamada opcionales. Debe estar totalmente proporcionado (uno por texto) u omitido para todos los textos. Los ID devueltos coinciden con estos valores cuando se proporcionan.
  • thread_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • user_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • agent_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • roles str | None | list[str | None]: rol de chat opcional para los registros de mensajes.
  • timestamps str | None | list[str | None]: registro de hora opcional o registros de hora por registro.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None: asignación de metadatos opcional o asignaciones de metadatos por registro. Los metadatos pueden incluir "content" como origen de reserva para los valores de texto omitidos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas del almacén reenviadas por API de nivel superior.
• Devoluciones: inserte identificadores para cada elemento de contenido de entrada. Estos coinciden con record_ids cuando se proporcionan; de lo contrario, almacena identificadores de generación.
• Tipo de devolución: list[str]

Ejemplos

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

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 y registros de memoria escritos.

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 al almacén de memoria.

• Parámetros:
  • contents list[str | None]: cargas útiles de texto que se van a almacenar. Estos valores también se utilizan para calcular la incrustación, a menos que se proporcionen index_texts o embeddings. Cuando se omite un elemento (None), los almacenes lo resuelven a partir de la clave de metadatos "content" cuando está disponible; de lo contrario, se mantiene el contenido vacío.
  • record_type str: etiqueta de tipo de registro para los registros almacenados (por ejemplo, "message", "memory", guideline, fact o preference).
  • index_texts list[str]: cargas útiles alternativas opcionales que se usan solo para incrustar/indexar. Cuando se proporciona, debe tener la misma longitud que contents.
  • embeddings list[list[float]] | list[ndarray]: vectores de incrustación precalculados opcionales alineados con contents. Cuando se proporciona, las tiendas deben utilizar estos vectores directamente y no deben llamar al embebido. Cuando se omite, el almacén utiliza el embebido solo para cargas útiles de indexación que no estén vacías; las cadenas vacías explícitas se almacenan sin embebidas de fragmentos.
  • record_ids str | None | list[str] | list[None]: ID de registro visibles para el emisor de llamada opcionales. Debe ser totalmente proporcionado (uno por texto) u omitido para todos los textos. Los ID devueltos coinciden con estos valores cuando se proporcionan. Cuando se omite, el almacén genera ID del lado del cliente.
  • thread_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • user_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • agent_ids str | None | list[str | None]: identificadores de ámbito opcionales almacenados con los registros.
  • roles str | None | list[str | None]: rol de chat opcional para los registros de mensajes.
  • timestamps str | None | list[str | None]: registros de hora de eventos proporcionados por el emisor de llamada opcional.
  • 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 para los valores de texto omitidos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas del almacén. Las claves soportadas actualmente incluyen batch_size para los lotes executemany de Oracle.
• Devoluciones: inserte identificadores para cada elemento de contenido de entrada. Estos coinciden con record_ids cuando se proporcionan; de lo contrario, almacena los ID generados de devolución.
• Tipo de devolución: list[str]

Ejemplos

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

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.
• Devoluciones: identificador del registro de perfil de agente insertado.
• Tipo de retorno: str

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.
• Devoluciones: identificador del registro de perfil de usuario insertado.
• Tipo de devolución: str

Ejemplos

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

método delete

Suprimir una fila de registro vectorial gestionada y sus filas de fragmentos por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro cuya tabla gestionada se debe dirigir, como "message", "memory", "guideline", "fact" o "preference"
  • record_id str: identificador de la fila que se va a eliminar.
• Devoluciones: número de filas eliminadas (0 cuando no se encontró el identificador).
• Tipo de devolución: int

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 de fragmentos y registros vectoriales asociados.

• Parámetros: thread_id str: identificador de thread cuyas filas se deben eliminar (incluidas las filas secundarias suprimidas en cascada).
• Devoluciones: número de filas de thread suprimidas (0 o 1).
• Tipo de devolución: int

Ejemplos

store.delete_thread("c1")
0

método get

Recuperar un mensaje o memoria almacenados por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro que se resuelve en una fila de registro vectorial gestionada, como "message", "memory", "guideline", "fact" o "preference".
  • 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" o "preference").
  • limit int: cantidad máxima de registros que se deben devolver.
  • 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 sin ámbito en la dimensión de thread.
  • 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 sin ámbito en la dimensión de usuario.
  • 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 sin ámbito en la dimensión de agente.
  • 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]

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']

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 deben incluir. Cuando se omite, la búsqueda cubre cualquier tipo de registro.
  • 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 o preference)
  • record_id str: identificador de la fila de mensaje o memoria que se va a 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.