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 un nuevo manejador de threads.

• 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.
  • 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 extraerá las memorias relevantes de cada mensaje agregado y las almacenará como record_type="memory".
  • 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.
  • context_summary_update_frequency: int número de mensajes tras los cuales se debe actualizar el resumen de contexto. Establézcalo en -1 para resumir solo una vez por cada llamada add_messages mediante el lote completo de mensajes recién agregados. Se vuelve a utilizar la misma cadencia para refrescar los metadatos de resumen de thread durante las escrituras de transcripción.
  • memory_extraction_frequency en 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.
  • memory_extraction_token_limit int: tamaño máximo, en tokens, de los indicadores utilizados en la extracción de memoria. Las peticiones de datos más largas se truncarán. Si es negativo o 0, no se realiza ningún truncamiento.
  • 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: indica si se debe mantener un resumen de ejecución compacto del thread. Cuando se activa y se proporciona llm, el resumen se actualiza según context_summary_update_frequency. El resumen actual se proporciona como contexto al extraer recuerdos.
  • cliente Any | None

Ejemplos

from oracleagentmemory.core import OracleAgentMemory
db_pool = ...
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    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.
  • 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.
  • **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 retorno: str

Ejemplos

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

método add_messages

Agregar mensajes al hilo y indexarlos.

• 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).
  • **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.
• Tipo de devolución: list[str]

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.

• Parámetros:
  • mensajes list[Message | MessageT]
  • store_kwargs Any
• Tipo de devolución: list[str]

método delete_memory

Suprimir un registro de memoria de este thread exacto por identificador.

• Parámetros: memory_id str: identificador de memoria. Solo se suprimen las memorias 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 eliminados (0 o 1). Devuelve 0 cuando el identificador no existe o pertenece a un thread diferente.
• Tipo de devolución: int

Notas

La supresión correcta borra el estado derivado de resumen de subproceso, de modo que más adelante se vuelven a crear el resumen y las llamadas de tarjeta de contexto a partir de la transcripción restante. Las memorias derivadas no se eliminan automáticamente porque las memorias extraídas no persisten actualmente por mensaje.

Ejemplos

thread.delete_message("123")
0

método get_context_card

Devolver una tarjeta de contexto similar a XML para el thread.

Prefiera 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.
  • max_relevant_results int: número máximo de registros duraderos recuperados que se deben incluir.
  • max_recent_messages int: número máximo de mensajes raw finales para incrustar textualmente.
  • **kwargs (cualquiera): reservado para futuras opciones de tarjeta contextual. Los argumentos de palabra clave inesperados generan TypeError.
• Devoluciones: tarjeta que contiene un resumen de contexto de thread basado en los mensajes más recientes.
• Tipo de devolución: str

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()
True

method get_context_card_async (async)

Devolver de forma asíncrona una tarjeta de contexto similar a XML 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.
  • max_relevant_results int: número máximo de registros duraderos recuperados que se deben incluir.
  • max_recent_messages int: número máximo de mensajes raw finales para incrustar textualmente.
  • **kwargs (cualquiera): reservado para futuras opciones de tarjeta contextual. Los argumentos de palabra clave inesperados generan TypeError.
• Devoluciones: tarjeta que contiene un resumen de contexto de thread basado en los mensajes más recientes.
• Tipo de devolución: str

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'

método get_summary

Devolver un resumen de mejor esfuerzo del hilo.

Prefiera 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 flexible. 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.
• Devuelve: un mensaje del asistente que contiene el resumen o una lista vacía si el thread no tiene mensajes.
• Tipo de devolución: list[Mensaje]

Ejemplos

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
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 flexible. Cuando se omite, se aplica un valor por defecto delimitado. Los valores positivos solo se truncan 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.
• Devuelve: un mensaje del asistente que contiene el resumen o una lista vacía si el thread no tiene mensajes.
• Tipo de devolución: list[Mensaje]

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