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.
  • 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_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 del 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.
  • 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 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.
  • context_card_token_limit int: tamaño máximo, en tokens, de las peticiones de datos del LLM utilizadas para el resumen de tarjetas de contexto. El valor por defecto es tokens 100_000. Los campos más largos se truncan. Si es negativo o 0, el truncamiento de petición de datos está desactivado.
  • 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

import oracledb

from oracleagentmemory.core import OracleAgentMemory
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,
    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'

method add_memory_async (async)

Agregue una memoria de forma asíncrona.

• Parámetros:
  • content str: contenido de memoria que se va a almacenar.
  • 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.
  • **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.

• 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

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. Sólo 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 las memorias extraídas no persisten en la procedencia por mensaje, por lo que pueden seguir siendo buscables o afectar a 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.

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

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.
  • 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.
• Devuelve: un objeto de tarjeta de contexto para el thread.
• Tipo De Retorno: OracleContextCard

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.

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.
• 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 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.
• 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.
  • record_types list[str]: lista opcional de tipos de registro que se deben incluir, como "memory" o "message".
  • 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, o si max_results es menor que 1.

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.

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".
  • 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, o si max_results es menor que 1.

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.

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.

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