Threads

Esta página presenta el identificador de thread de Oracle concreto junto con el tipo de ayuda de mensaje orientado al desarrollador.

Thread de Oracle

clase oracleagentmemory.core.OracleThread

Bases: IThread

Thread respaldado por un almacén de Oracle.

Esta implantación incrusta y almacena tanto mensajes de thread como memorias agregadas manualmente y, a continuación, soporta la búsqueda de similitud en todos los registros almacenados.

Notas

• Los mensajes se almacenan como registros individuales (un registro por mensaje).
• La búsqueda se puede restringir al thread actual o permitir que devuelva resultados de cualquier thread (controlado por el cliente).

Cree una nueva instancia de OracleThread.

• Parámetros:
  • store OracleMemoryStore: backend de almacén compartido utilizado para mantener los registros incrustados.
  • thread_id str: identificador de thread. Si no se proporciona, se genera un UUID.
  • user_id str: identificador de usuario asociado con el subproceso. Si se omite, se genera un UUID.
  • agent_id str: identificador de agente asociado con el thread. Si se omite, se genera un UUID.
  • metadata dict[str, Any] | None: metadatos opcionales similares a JSON asociados con el thread.
  • persist_messages_in_config bool: indica si _to_config debe incluir instantáneas de mensajes raw recientes. Se define automáticamente en False para los threads que utilizan el almacén de base de datos para evitar exportar contenido de la tabla de mensajes mediante la configuración de thread.
  • LLM ILlm | None: adaptador LLM opcional que se utiliza para la extracción de memoria y las actualizaciones de resumen de contexto. Cuando se proporciona, add_messages extrae las memorias relevantes de cada mensaje agregado y las almacena como registros de memoria escritos ("memory", "guideline", "fact" o "preference").
  • memory_extraction_config MemoryExtractionConfig: configuración opcional de extracción de memoria en el nivel de thread. Utilícelo para controlar la configuración de extracción automática, como el modo de extracción, el comportamiento de resumen, los límites de extracción y si la extracción automática está activada. Transfiera esta configuración agrupada o los parámetros de extracción en línea en desuso, no ambos. Cuando se omite, OracleThread() independiente utiliza los valores por defecto del SDK para los campos de extracción y mantiene activados los resúmenes de contexto.

  • memory_extraction_window int:

    Número de mensajes más recientes (incluido el recién agregado) que se deben proporcionar como contexto para el LLM durante la extracción. Defina esta opción en -1 para extraer solo una vez por cada llamada add_messages mediante el lote completo de mensajes recién agregados. El valor por defecto es -1.

    Anticuada

    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_extraction_config en su lugar.

  • context_summary_update_frequency: int

    Número de mensajes tras los cuales se debe actualizar el resumen de contexto de extracción. Establézcalo en -1 para resumir solo una vez por cada llamada add_messages mediante el lote completo de mensajes recién agregados. El valor por defecto es -1.

    Información: 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_extraction_config en su lugar.

  • memory_extraction_frequency: int.

    Número de mensajes tras los cuales se dispara la extracción de memoria. Defina esta opción en -1 para extraer solo una vez por cada llamada add_messages mediante el lote completo de mensajes recién agregados.

    Información: 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_extraction_config en su lugar.

  • memory_extraction_token_limit int:

    Tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para la extracción de memoria y la ejecución de actualizaciones de resumen. Los campos más largos se truncan. Si es negativo o 0, el truncamiento de petición de datos está desactivado.

    Información: 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_extraction_config en su lugar.

  • context_card_token_limit int: presupuesto máximo de token de entrada para la petición de datos del LLM que se utiliza para crear el resumen y la lista de temas incluidos en la tarjeta de contexto. El valor por defecto es 100_000; los valores son menor o igual que 0 para desactivar el truncamiento de petición de datos.
  • context_card_type_search_concurrency int: número máximo de búsquedas de registros similares a la memoria que se deben ejecutar simultáneamente al crear una tarjeta contextual con min_relevant_results_by_type. El valor por defecto es 5.
  • max_message_token_length int: tamaño máximo, en tokens, de la copia de tiempo de petición de datos de cada mensaje utilizado durante la extracción de memoria respaldada por LLM y las actualizaciones de resumen de contexto. El contenido del mensaje almacenado permanece sin cambios. Si es negativo o 0, no se realiza ningún acortamiento de tiempo de solicitud. Si se proporciona un LLM, las copias de petición de datos de gran tamaño se resumen en lugar de truncarse.
  • message_shortening_input_token_limit int: tamaño máximo, en tokens, del extracto de mensaje enviado al LLM al acortar las copias de petición de datos de gran tamaño. El valor por defecto es tokens 30_000. Si es negativo o 0, no se aplica ningún límite de salida durante el acortamiento basado en LLM.

  • enable_context_summary bool:

    Si se debe mantener un resumen de ejecución compacto del thread. Cuando está activado y se proporciona llm, el resumen se actualiza según context_summary_update_frequency. El resumen actual se proporciona como contexto al extraer recuerdos. El valor por defecto es True para OracleThread() independiente.

    Información: 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_extraction_config en su lugar.

  • memory_extraction_custom_instructions str | None:

    Instrucciones personalizadas opcionales agregadas a la petición de datos del sistema de extracción automática de memoria para este thread.

    Información: 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_extraction_config en su lugar.

  • memory_extraction_inherit_message_metadata bool | Sequence[str]:

    Si las memorias extraídas automáticamente heredan metadatos de los mensajes de origen. Transfiera True para heredar todos los metadatos de mensajes, una secuencia no de cadena de claves de metadatos de mensajes de nivel superior para heredar solo esas claves o False para desactivar la herencia. El valor por defecto es True. Si una transferencia de extracción utiliza varios mensajes de origen, los metadatos seleccionados deben coincidir entre esos mensajes.

    Información: 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_extraction_config en su lugar.

  • cliente OracleAgentMemory | None

Ejemplos

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

método add_memory

Agregue una entrada de memoria manual e indíquela.

• Parámetros:
  • content str: contenido de texto que se va a almacenar como memoria.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker: categoría de memoria para almacenar. Los valores soportados son "memory", "fact", "guideline" y "preference". Cuando se omite, el contenido se almacena como un "memory" general.
  • user_id str: sustitución de identificador de usuario opcional.
  • agent_id str: sustitución de identificador de agente opcional.
  • thread_id str: sustitución de identificador de thread opcional.
  • memory_id str: identificador estable proporcionado por el emisor de llamada opcional para esta fila de memoria.
  • metadata dict[str, Any] | None: metadatos opcionales que se mantienen con la memoria almacenada.
  • timestamp str | None: registro de hora opcional que se guarda para esta memoria. Representa cuándo se creó la memoria. Cuando se omite o None, el almacén utiliza la hora actual. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, proporcione un valor de registro de hora ISO-8601 concreto. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • ttl_days int | None: duración opcional del tiempo de vida en días. Omita este argumento para utilizar la duración de tiempo de actividad por defecto del esquema. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para almacenar una memoria 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.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación de la base de datos o TimeToLiveAnchor.TIMESTAMP para el registro de hora de la memoria. La caducidad anclada en el registro de hora requiere un registro de hora ISO-8601 concreto para esta memoria. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • **store_kwargs (Cualquiera): opciones de escritura específicas del almacén reenviadas al almacén de copia de seguridad.
• Devoluciones: identificador del registro de memoria insertado.
• Tipo de devolución: str

Ejemplos

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

method add_memory_async (async)

Agregue una memoria de forma asíncrona.

• Parámetros:
  • content str: contenido de memoria que se va a almacenar.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker: categoría de memoria para almacenar. Los valores soportados son "memory", "fact", "guideline" y "preference". Cuando se omite, el contenido se almacena como un "memory" general.
  • user_id str: sustitución de ámbito de usuario opcional.
  • agent_id str: sustitución de ámbito de agente opcional.
  • thread_id str: sustitución de ámbito de thread opcional.
  • memory_id str: identificador de memoria opcional proporcionado por el emisor de llamada. Cuando se omite, las tiendas generan un ID.
  • metadata dict[str, Any] | None: metadatos opcionales que se mantienen con la memoria almacenada.
  • timestamp str | None: registro de hora opcional que se guarda para esta memoria. Representa cuándo se creó la memoria. Cuando se omite o None, el almacén utiliza la hora actual.
  • ttl_days int | None: duración opcional del tiempo de vida en días. Omita este argumento para utilizar la duración de tiempo de actividad por defecto del esquema o transfiera None para una memoria que no caduque.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT o TimeToLiveAnchor.TIMESTAMP.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén de copia de seguridad.
• Tipo de devolución: str

método add_messages

Agregar mensajes al hilo y indexarlos.

En el modo de extracción en segundo plano, este método se devuelve después de insertar los mensajes raw y de intentar la extracción en segundo plano en segundo plano.

• Parámetros:
  • messages list[Message | MessageT]: lista de mensajes que se van a agregar. Los mensajes pueden ser objetos Message o diccionarios con role y content (y id opcional).
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: metadatos opcionales compartidos o por mensaje que se conservan. Cuando se omite, se utilizan los metadatos embebidos en cada mensaje.
  • ttl_days int | None | list[int | None]: duración opcional del tiempo de vida en días para los mensajes agregados. Omita este argumento para utilizar la duración de tiempo de actividad por defecto del esquema. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para crear mensajes que no caduquen 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 aplican al lote completo.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación de la base de datos o TimeToLiveAnchor.TIMESTAMP para cada registro de hora de mensaje. La caducidad anclada en el registro de hora requiere un registro de hora ISO-8601 concreto para cada mensaje afectado. Cuando se omite, los mensajes caducan en relación con TimeToLiveAnchor.CREATED_AT. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • **store_kwargs (Cualquiera): opciones de escritura específicas del almacén reenviadas al almacén de copia de seguridad.
• Devoluciones: identificadores de los registros de mensajes insertados. En el modo de extracción en segundo plano, es posible que el trabajo de extracción automática aún se esté ejecutando cuando se devuelvan estos identificadores.
• Tipo de devolución: list[str]

Notas

En MemoryExtractionMode.BACKGROUND, los mensajes raw se mantienen antes de que se almacenen las memorias extraídas. Si la extracción en segundo plano no se pone en cola o si una espera de capacidad de cola configurada alcanza su timeout, los mensajes raw insertados permanecen almacenados y la llamada continúa sin memorias extraídas o emite TimeoutError, según background_extraction_queue_full_behavior.

Ejemplos

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

method add_messages_async (async)

Agregar mensajes al thread de forma asíncrona e indexarlos.

En el modo de extracción en segundo plano, este método se devuelve después de insertar los mensajes raw y de intentar la extracción en segundo plano en segundo plano.

En MemoryExtractionMode.BACKGROUND, los mensajes raw se mantienen antes de que se almacenen las memorias extraídas. Si la extracción en segundo plano no se pone en cola o si una espera de capacidad de cola configurada alcanza su timeout, los mensajes raw insertados permanecen almacenados y la llamada continúa sin memorias extraídas o emite TimeoutError, según background_extraction_queue_full_behavior.

• Parámetros:
  • mensajes list[Message | MessageT]
  • 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 delete_memory

Eliminar un registro similar a la memoria (por ejemplo, una memoria, un hecho, una preferencia o una directriz) de este thread exacto por identificador.

• Parámetros: memory_id str: identificador de memoria. Solo se suprimen los registros similares a la memoria (memory, guideline, fact, preference) cuyo thread_id almacenado coincida exactamente con este thread.
• Devoluciones: número de registros eliminados (0 o 1). Devuelve 0 cuando el identificador no existe o pertenece a un thread diferente.
• Tipo de devolución: int

Ejemplos

thread.delete_memory("456")
0

método delete_message

Eliminar un registro de mensaje de este hilo exacto por identificador.

• Parámetros: message_id str – Identificador de mensaje. Solo se suprimen los mensajes cuyo thread_id almacenado coincida exactamente con este thread.
• Devoluciones: número de registros de mensajes eliminados (0 o 1). Devuelve 0 cuando el identificador no existe o pertenece a un thread diferente.
• Tipo de devolución: int

Notas

Al eliminar un mensaje, solo se elimina el registro de mensaje sin formato. Las memorias derivadas no se eliminan porque todavía no rastreamos qué memorias extraídas provienen de qué mensaje, por lo que pueden seguir siendo buscables o aún afectar la salida de la tarjeta de contexto. Utilice OracleAgentMemory.delete_thread() para suprimir el thread junto con sus mensajes y memorias asociados.

Ejemplos

thread.delete_message("123")
0

método get_context_card

Devolver un objeto de tarjeta de contexto para el thread.

Preferir get_context_card_async cuando una implementación respaldada por LLM puede realizar E/S de red remota.

• Parámetros:
  • fallback_message_count int: número de mensajes recientes que se utilizarán al derivar el texto de resumen de reserva para la recuperación y la representación. Cuando se omite, se resuelve en 5.
  • max_relevant_results int: número máximo de registros duraderos recuperados que se deben incluir. Cuando se omite, se resuelve en 5 a menos que se proporcione min_relevant_results_by_type; en ese caso, se resuelve en un máximo de 5 y la suma de los mínimos por tipo solicitados.
  • max_recent_messages int: número máximo de mensajes raw finales para incrustar textualmente. Cuando se omite, se resuelve en 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker: mínimos opcionales por tipo para registros similares a la memoria relevantes incluidos en la tarjeta de contexto. Los tipos solicitados se buscan primero y las ranuras max_relevant_results restantes se rellenan a partir de todos los tipos de registro similares a la memoria admitidos. Las claves admitidas son "memory", "fact", "guideline" y "preference".
  • **kwargs (cualquiera): reservado para futuras opciones de tarjeta contextual. Los argumentos de palabra clave inesperados generan TypeError.
• Devoluciones: objeto de tarjeta de contexto que contiene un resumen de contexto de thread basado en los mensajes más recientes. Utilice OracleContextCard.content para acceder al texto similar a XML presentado.
• Tipo De Retorno: OracleContextCard

Notas

Esto utiliza el ámbito de búsqueda predeterminado del thread con exact_thread_match=False, por lo que se pueden incluir memorias relevantes de otros threads para el mismo usuario/agente.

Ejemplos

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async (async)

Devolver de forma asíncrona un objeto de tarjeta de contexto para el thread.

• Parámetros:
  • fallback_message_count int: número de mensajes recientes que se utilizarán al derivar el texto de resumen de reserva para la recuperación y la representación. Cuando se omite, se resuelve en 5.
  • max_relevant_results int: número máximo de registros duraderos recuperados que se deben incluir. Cuando se omite, se resuelve en 5 a menos que se proporcione min_relevant_results_by_type; en ese caso, se resuelve en un máximo de 5 y la suma de los mínimos por tipo solicitados.
  • max_recent_messages int: número máximo de mensajes raw finales para incrustar textualmente. Cuando se omite, se resuelve en 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker: mínimos opcionales por tipo para registros similares a la memoria relevantes incluidos en la tarjeta de contexto. Los tipos solicitados se buscan primero y las ranuras max_relevant_results restantes se rellenan a partir de todos los tipos de registro similares a la memoria admitidos. Las claves admitidas son "memory", "fact", "guideline" y "preference".
  • **kwargs (cualquiera): reservado para futuras opciones de tarjeta contextual. Los argumentos de palabra clave inesperados generan TypeError.
• Devuelve: un objeto de tarjeta de contexto para el thread.
• Tipo De Retorno: OracleContextCard

Ejemplos

card = await thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
)
len(card.relevant_results or []) <= 5
True

método get_messages

Devolver mensajes almacenados para este tema.

• Parámetros:
  • start int | None: índice de inicio (basado en 0). Cuando se omite junto con end, se devuelve la ventana delimitada más reciente.
  • end int | None: índice final (exclusivo). Cuando se omite, se devuelve una ventana delimitada de los mensajes más recientes. Transfiera None o -1 para solicitar explícitamente todos los mensajes de start en adelante.
• Devoluciones: mensajes en orden cronológico.
• Tipo de devolución: list[Mensaje]

Ejemplos

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

method get_messages_async (async)

Devolver mensajes de thread sin procesar de forma asíncrona.

• Parámetros:
  • start int | None: índice de inicio opcional.
  • end int | None: índice final opcional.
• Devoluciones: objetos de mensaje raw.
• Tipo de devolución: list[Mensaje]

método get_summary

Devolver un resumen de mejor esfuerzo del hilo.

Preferir get_summary_async cuando una implementación respaldada por LLM puede realizar E/S de red remota.

• Parámetros:
  • excepto_último int: número de mensajes más recientes que se deben excluir del resumen.
  • token_budget int: presupuesto de token de software. Cuando se omite, se aplica un valor por defecto delimitado. Los valores positivos se truncan sólo cuando el resumen con formato supera el presupuesto estimado por _estimate_tokens(); el texto devuelto se limita a los caracteres int(token_budget * 3.5). Los valores no positivos desactivan el límite de salida.
  • **kwargs (cualquiera): reservado para opciones de resumen futuras. Los argumentos de palabra clave inesperados generan TypeError.
• Devoluciones: objeto de resumen que contiene el texto de resumen del hilo sintetizado.
• Tipo de retorno: OracleSummary

Ejemplos

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

method get_summary_async (async)

Devolver de forma asíncrona un resumen de mejor esfuerzo del thread.

• Parámetros:
  • excepto_último int: número de mensajes más recientes que se deben excluir del resumen.
  • token_budget int: presupuesto de token de software. Cuando se omite, se aplica un valor por defecto delimitado. Los valores positivos se truncan sólo cuando el resumen con formato supera el presupuesto estimado por _estimate_tokens(); el texto devuelto se limita a los caracteres int(token_budget * 3.5). Los valores no positivos desactivan el límite de salida.
  • **kwargs (cualquiera): reservado para opciones de resumen futuras. Los argumentos de palabra clave inesperados generan TypeError.
• Devoluciones: objeto de resumen que contiene el texto de resumen del hilo sintetizado.
• Tipo de retorno: OracleSummary

método search

Búsqueda sincrónica de registros relevantes para una consulta.

• Parámetros:
  • query str: cadena de consulta en lenguaje natural.
  • user_id str | None: sustitución de ámbito de usuario opcional. Los valores omitidos heredan el ámbito de usuario por defecto del thread.
  • agent_id str | None: sustitución de ámbito de agente opcional. Los valores omitidos heredan el ámbito de agente por defecto del thread.
  • thread_id str | None: sustitución de ámbito de thread opcional. Los valores omitidos heredan el identificador de thread actual del thread.
  • exact_user_match bool: indica si la coincidencia de usuarios debe ser estricta.
  • exact_agent_match bool: indica si la coincidencia de agentes debe ser estricta.
  • exact_thread_match bool: si la coincidencia de subprocesos debe ser estricta.
  • max_results int: número máximo opcional de resultados para devolver. Cuando se proporciona, debe ser al menos 1. La omisión de este argumento utiliza el valor por defecto de 10. La llamada puede devolver menos de max_results cuando existen menos registros coincidentes no vencidos.
  • record_types list[str]: lista opcional de tipos de registro que se deben incluir, como "memory" o "message".

  • metadata_filter dict[str, Any] | None:

    Asignación de filtro de metadatos opcional utilizada como filtro adicional después del filtrado de ámbito y tipo de registro. 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 de registro almacenados. Los diccionarios anidados coinciden recursivamente con los objetos de metadatos anidados. Los valores escalares y de lista deben coincidir exactamente; el orden y la longitud de la lista también deben coincidir. Omita este argumento o transfiera None para buscar sin filtrado de metadatos. Entre los ejemplos se incluyen metadata_filter={"source": "chat"} para un campo escalar, metadata_filter={"travel": {"need": "transit"}} para un campo anidado y metadata_filter={"tags": ["trip", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo. "$array_contains" coincide con un valor o con todos los valores de una lista. "$array_contains_any" coincide con al menos un valor de una lista. "$not" niega otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta sin formato. Las expresiones negativas coinciden cuando la expresión positiva falla, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope: ámbito de búsqueda predefinido opcional. Proporcione scope o el identificador explícito y los argumentos de coincidencia exacta, no ambos.
• Devoluciones: los resultados de búsqueda ordenados por relevancia decreciente.
• Tipo de devolución: list[SearchResult]
• Problemas: ValueError: si scope se combina con argumentos de identificador explícito o coincidencia exacta, si max_results es menor que 1 o si metadata_filter no es un diccionario ni None.

Notas

Los campos de ámbito omitidos heredan el ámbito de búsqueda por defecto de este thread: coincidencia exacta de usuario y agente más los valores user_id, agent_id y thread_id actuales de este thread. La búsqueda de subprocesos predeterminada deja intencionadamente exact_thread_match=False, por lo que puede devolver registros relevantes de otros subprocesos para el mismo usuario/agente. Transfiera exact_thread_match=True para restringir los resultados al thread actual. Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los valores None almacenados.

Los valores max_results explícitos deben ser al menos 1; al omitir el argumento se utiliza el valor por defecto de 10. Este es un límite superior: la llamada puede devolver menos de max_results resultados cuando los filtros son demasiado restrictivos, cuando hay menos registros coincidentes o debido al comportamiento de búsqueda específico de la implementación.

method search_async (async)

Busque de forma asíncrona registros relevantes para una consulta.

• Parámetros:
  • query str: cadena de consulta en lenguaje natural.
  • user_id str | None: sustitución de ámbito de usuario opcional. Los valores omitidos heredan el ámbito de usuario por defecto del thread.
  • agent_id str | None: sustitución de ámbito de agente opcional. Los valores omitidos heredan el ámbito de agente por defecto del thread.
  • thread_id str | None: sustitución de ámbito de thread opcional. Los valores omitidos heredan el identificador de thread actual del thread.
  • exact_user_match bool: indica si la coincidencia de usuarios debe ser estricta.
  • exact_agent_match bool: indica si la coincidencia de agentes debe ser estricta.
  • exact_thread_match bool: si la coincidencia de subprocesos debe ser estricta.
  • max_results int: número máximo opcional de resultados para devolver. Cuando se proporciona, debe ser al menos 1. La omisión de este argumento utiliza el valor por defecto de 10.
  • record_types list[str]: lista opcional de tipos de registro que se deben incluir, como "memory" o "message".

  • metadata_filter dict[str, Any] | None:

    Asignación de filtro de metadatos opcional utilizada como filtro adicional después del filtrado de ámbito y tipo de registro. 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 de registro almacenados. Los diccionarios anidados coinciden recursivamente con los objetos de metadatos anidados. Los valores escalares y de lista deben coincidir exactamente; el orden y la longitud de la lista también deben coincidir. Omita este argumento o transfiera None para buscar sin filtrado de metadatos. Entre los ejemplos se incluyen metadata_filter={"source": "chat"} para un campo escalar, metadata_filter={"travel": {"need": "transit"}} para un campo anidado y metadata_filter={"tags": ["trip", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo. "$array_contains" coincide con un valor o con todos los valores de una lista. "$array_contains_any" coincide con al menos un valor de una lista. "$not" niega otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta sin formato. Las expresiones negativas coinciden cuando la expresión positiva falla, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope: ámbito de búsqueda predefinido opcional. Proporcione scope o el identificador explícito y los argumentos de coincidencia exacta, no ambos.
• Devoluciones: los resultados de búsqueda ordenados por relevancia decreciente.
• Tipo de devolución: list[SearchResult]
• Problemas: ValueError: si scope se combina con argumentos de identificador explícito o coincidencia exacta, si max_results es menor que 1 o si metadata_filter no es un diccionario ni None.

Notas

Los campos de ámbito omitidos heredan el ámbito de búsqueda por defecto de este thread: coincidencia exacta de usuario y agente más los valores user_id, agent_id y thread_id actuales de este thread. La búsqueda de subprocesos predeterminada deja intencionadamente exact_thread_match=False, por lo que puede devolver registros relevantes de otros subprocesos para el mismo usuario/agente. Transfiera exact_thread_match=True para restringir los resultados al thread actual. Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los valores None almacenados.

Los valores max_results explícitos deben ser al menos 1; al omitir el argumento se utiliza el valor por defecto de 10. Este es un límite superior: la llamada puede devolver menos de max_results resultados cuando los filtros son demasiado restrictivos, cuando hay menos registros coincidentes o debido al comportamiento de búsqueda específico de la implementación.

método update_memory

Actualice un registro similar a la memoria que sea propiedad de este thread exacto.

• Parámetros:
  • memory_id str: identificador de memoria. Solo se actualizan los registros similares a la memoria (memory, guideline, fact, preference) cuyo thread_id almacenado coincida exactamente con este thread.
  • content str – Contenido de reemplazo opcional. Proporcione una cadena para sustituir el contenido almacenado. Cuando se omite, el contenido almacenado se conserva. No se admite la transferencia de None; omita content para mantener el valor actual o utilice delete_memory() para eliminar el registro.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Cuando se omite, los metadatos almacenados se conservan. Cuando se proporciona, sustituye el objeto de metadatos almacenado; esta API no fusiona en profundidad los metadatos.
  • timestamp str | None: nuevo registro de hora opcional para esta memoria. Representa cuándo se creó la memoria. Cuando se omite, el registro de hora almacenado se conserva. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se ha creado en la tienda. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, los registros de hora de sustitución deben ser cadenas ISO-8601. 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 para dejar la caducidad actual sin cambios a menos que se proporcione ttl_anchor. 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. Las memorias caducadas no están disponibles para esta API de thread y no se pueden refrescar.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación de memoria 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. Al proporcionar ttl_anchor sin ttl_days se utiliza la duración de tiempo de actividad por defecto del esquema. Cuando se omite ttl_anchor durante un refrescamiento, el thread 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.
  • **kwargs (Cualquiera): se rechazan los argumentos de palabras clave inesperados.
• Devoluciones: identificador del registro similar a la memoria actualizado.
• Tipo de devolución: str

method update_memory_async (async)

Actualizar un registro similar a la memoria de forma asíncrona.

• Parámetros:
  • memory_id str: identificador del registro similar a la memoria que se actualizará.
  • content str – Contenido de reemplazo opcional. Proporcione una cadena para sustituir el contenido almacenado. Cuando se omite, el contenido almacenado se conserva. No se admite la transferencia de None; omita content para mantener el valor actual o utilice delete_memory() para eliminar el registro.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Cuando se omite, los metadatos almacenados se conservan. Cuando se proporciona, sustituye el objeto de metadatos almacenado; esta API no fusiona en profundidad los metadatos.
  • timestamp str | None: nuevo registro de hora opcional para esta memoria. Representa cuándo se creó la memoria. Cuando se omite, el registro de hora almacenado se conserva. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se ha creado en la tienda.
  • 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. Al proporcionar ttl_anchor sin ttl_days se utiliza la duración de tiempo de actividad por defecto del esquema.
  • **kwargs (Cualquiera): se rechazan los argumentos de palabras clave inesperados.
• Devoluciones: identificador del registro similar a la memoria actualizado.
• Tipo de devolución: str

Ejemplos

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

método update_message

Actualizar un registro de mensaje raw propiedad de este thread exacto.

• Parámetros:
  • message_id str: identificador de mensaje. Solo se actualizan los mensajes cuyo thread_id almacenado coincida exactamente con este thread.
  • content str: contenido del mensaje de sustitución opcional. Proporcione una cadena para sustituir el contenido almacenado. Cuando se omite, el contenido almacenado se conserva. No se admite la transferencia de None.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Cuando se omite, los metadatos almacenados se conservan. Cuando se proporciona, sustituye el objeto de metadatos almacenado; esta API no fusiona en profundidad los metadatos.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento para dejar la caducidad actual sin cambios a menos que se proporcione ttl_anchor. 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. Los mensajes caducados no están disponibles para esta API de thread y no se pueden refrescar.
  • 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 mensaje o TimeToLiveAnchor.TIMESTAMP para el registro de hora del evento almacenado. Al proporcionar ttl_anchor sin ttl_days se utiliza la duración de tiempo de actividad por defecto del esquema. Cuando se omite ttl_anchor durante un refrescamiento, el thread utiliza TimeToLiveAnchor.CREATED_AT. Los refrescamientos con anclaje de registro de hora requieren un registro de hora de mensaje ISO-8601 almacenado existente. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • **kwargs (Cualquiera): se rechazan los argumentos de palabras clave inesperados.
• Devoluciones: identificador del registro de mensaje actualizado.
• Tipo de devolución: str

Notas

Los campos omitidos se conservan del registro almacenado. El rol almacenado y el registro de hora permanecen sin cambios. La edición del contenido actualiza el historial de mensajes raw y, cuando la extracción automática está activada, puede hacer que el SDK vuelva a extraer las memorias del mensaje editado y del historial anterior. En el modo INLINE, esa extracción finaliza antes de que se devuelva este método. En el modo BACKGROUND, este método se devuelve después de que la actualización del mensaje raw se realiza correctamente y se intenta la extracción en segundo plano. Este trabajo de seguimiento no afecta a la frecuencia de extracción normal que utilizan las llamadas add_messages() posteriores. Las memorias extraídas existentes permanecen en su lugar mientras que las memorias recién extraídas del contenido editado pueden agregarse. Debido a que la actualización del mensaje sin formato y las escrituras de memoria extraídas posteriores no se producen atómicamente, las memorias extraídas aún pueden reflejar el contenido del mensaje anterior si el trabajo en segundo plano no se pone en cola, si una espera de capacidad de cola configurada alcanza su timeout o si falla el trabajo de extracción posterior. Además, tenga en cuenta que las memorias extraídas existentes mantienen su caducidad original cuando cambia el TTL de un mensaje de origen.

Ejemplos

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async (async)

Actualice un registro de mensaje raw propiedad de este thread exacto de forma asíncrona.

• Parámetros:
  • message_id str: identificador de mensaje. Solo se actualizan los mensajes cuyo thread_id almacenado coincida exactamente con este thread.
  • content str: contenido del mensaje de sustitución opcional. Proporcione una cadena para sustituir el contenido almacenado. Cuando se omite, el contenido almacenado se conserva. No se admite la transferencia de None.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Cuando se omite, los metadatos almacenados se conservan. Cuando se proporciona, sustituye el objeto de metadatos almacenado; esta API no fusiona en profundidad los metadatos.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento para dejar la caducidad actual sin cambios a menos que se proporcione ttl_anchor. 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. Los mensajes caducados no están disponibles para esta API de thread y no se pueden refrescar.
  • 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 mensaje o TimeToLiveAnchor.TIMESTAMP para el registro de hora del evento almacenado. Al proporcionar ttl_anchor sin ttl_days se utiliza la duración de tiempo de actividad por defecto del esquema. Los refrescamientos con anclaje de registro de hora requieren un registro de hora de mensaje ISO-8601 almacenado existente. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • **kwargs (Cualquiera): se rechazan los argumentos de palabras clave inesperados.
• Devoluciones: identificador del registro de mensaje actualizado.
• Tipo de devolución: str

Notas

Los campos omitidos se conservan del registro almacenado. El rol almacenado y el registro de hora permanecen sin cambios. La edición del contenido actualiza el historial de mensajes raw y, cuando la extracción automática está activada, puede hacer que el SDK vuelva a extraer las memorias del mensaje editado y del historial anterior. En el modo INLINE, esa extracción finaliza antes de que se devuelva este método. En el modo BACKGROUND, este método se devuelve después de que la actualización del mensaje raw se realiza correctamente y se intenta la extracción en segundo plano. Este trabajo de seguimiento no afecta a la frecuencia de extracción normal que utilizan las llamadas add_messages() posteriores. Las memorias extraídas existentes permanecen en su lugar mientras que las memorias recién extraídas del contenido editado pueden agregarse. Debido a que la actualización del mensaje sin formato y las escrituras de memoria extraídas posteriores no se producen atómicamente, las memorias extraídas aún pueden reflejar el contenido del mensaje anterior si el trabajo en segundo plano no se pone en cola, si una espera de capacidad de cola configurada alcanza su timeout o si falla el trabajo de extracción posterior. Además, tenga en cuenta que las memorias extraídas existentes mantienen su caducidad original cuando cambia el TTL de un mensaje de origen.

Ejemplos

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
run_async_in_sync(
    partial(thread.update_message_async, message_id, content="Edited message")
) == message_id
True

método wait_for_memory_extraction

Espere a una extracción de memoria en segundo plano anterior para este thread.

Este método espera a que se inicie la extracción en segundo plano mediante llamadas add_messages(), add_messages_async(), update_message() o update_message_async() anteriores en este thread a través del mismo componente de memoria de agente. Si una de esas llamadas ya está terminando, este método incluye la extracción que comienza antes de esperar.

El método no espera a que se inicie la extracción después de que comience esta espera, a que se inicie la extracción por un componente de memoria de agente diferente o a que se ejecute la extracción en otro proceso. Los fallos de extracción cuentan como finalizados para esta espera.

• Parámetros: timeout float | None: número máximo opcional de segundos para esperar. El valor por defecto es 300. Transfiera None para esperar hasta que la extracción pendiente para este thread haya finalizado.
• Subidas: TimeoutError: se genera cuando el timeout caduca antes de que finalice la extracción en segundo plano anterior.
• Tipo de devolución: ninguno

Ejemplos

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (async)

Espere de forma asíncrona la extracción de memoria en segundo plano anterior.

Este método sigue el mismo comportamiento que wait_for_memory_extraction().

• Parámetros: timeout float | None: número máximo opcional de segundos para esperar. El valor por defecto es 300. Transfiera None para esperar indefinidamente.
• Subidas: TimeoutError: se genera cuando el timeout caduca antes de que finalice la extracción en segundo plano anterior.
• Tipo de devolución: ninguno

Ejemplos

await thread.wait_for_memory_extraction_async(timeout=10)

Nota: delete_message() solo suprime la fila de mensaje raw. Los recuerdos derivados pueden seguir siendo buscables o aparecer en las tarjetas de contexto. Utilice OracleAgentMemory.delete_thread() para suprimir el thread junto con sus mensajes y memorias asociados. La supresión de thread de nivel de cliente espera la extracción en segundo plano aceptada anteriormente ya conocida para ese thread, pero no es una barrera de simultaneidad global para otras operaciones en el mismo thread mientras la supresión está en curso.

Mensajes

clase oracleagentmemory.apis.thread.Message

Bases: object

• Parámetros:
  • rol str
  • contenido str
  • registro de hora str | None
  • metadatos dict[str, Any] | None
  • id str | None

Tarjetas de contexto

clase oracleagentmemory.apis.contextcard.ContextCard

Bases: ABC

Objeto abstracto de tarjeta de contexto devuelto por las API de thread.

property content (resumen)

• Tipo de devolución: str
• Descripción: devuelve el texto de la tarjeta contextual representada.

clase oracleagentmemory.core.contextcard.OracleContextCard

Bases: ContextCard

Tarjeta de contexto devuelta por un thread de Oracle.

• Parámetros:
  • summary str: texto de resumen incrustado en la tarjeta.
  • topics Sequence[str] | None: temas de recuperación opcionales asociados con el thread.
  • relevant_results Sequence[SearchResult] | None: registros duraderos recuperados opcionales incluidos en la tarjeta.
  • recent_messages Sequence[Message] | None: mensajes raw recientes opcionales representados en la tarjeta.
  • message_format str: plantilla interna que se utiliza al representar recent_messages.

propiedad content

• Tipo de devolución: str

• Descripción: devuelve el texto de la tarjeta contextual representada.

• Devoluciones: texto de tarjeta contextual representado similar a XML adecuado para el ensamblaje de la petición de datos.
• Tipo de devolución: str

Ejemplos

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

propiedad formatted_content

• Tipo de devolución: str

• Descripción: devuelve el texto de la tarjeta contextual representada utilizado en los flujos de creación de peticiones de datos.

• Devoluciones: texto de tarjeta contextual representado similar a XML.
• Tipo de devolución: str

Ejemplos

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

Resúmenes

clase oracleagentmemory.apis.summary.Summary

Bases: ABC

Objeto abstracto de resumen de thread devuelto por las API de thread.

property content (resumen)

• Tipo de devolución: str
• Descripción: devuelve el texto de resumen sintetizado.

clase oracleagentmemory.core.summary.OracleSummary

Bases: Summary

Resumen devuelto por un thread de Oracle.

• Parámetros: content str: texto de resumen sintetizado a partir de la transcripción del hilo.

Ejemplos

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

propiedad content

• Tipo de devolución: str

• Descripción: devuelve el texto de resumen sintetizado.

• Devoluciones: texto de resumen para el thread.
• Tipo de devolución: str

Ejemplos

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

propiedad formatted_content

• Tipo de devolución: str

• Descripción: devuelve el texto de resumen representado utilizado en los flujos de creación de peticiones de datos.

• Devoluciones: texto de resumen representado.
• Tipo de devolución: str

Ejemplos

OracleSummary(content="Thread recap").formatted_content
'Thread recap'