Threads

Esta página apresenta o identificador de thread concreto do Oracle junto com o tipo de auxiliar de mensagem voltado para o desenvolvedor.

Thread Oracle

classe oracleagentmemory.core.OracleThread

Bases: IThread

Thread apoiado por um armazenamento Oracle.

Esta implementação incorpora e armazena mensagens de thread e memórias adicionadas manualmente e, em seguida, suporta pesquisa de similaridade em todos os registros armazenados.

Observações

• As mensagens são armazenadas como registros individuais (um registro por mensagem).
• A pesquisa pode ser restrita ao thread atual ou pode retornar resultados de qualquer thread (controlado pelo cliente).

Crie um novo identificador de thread.

• Parâmetros:
  • store OracleMemoryStore – Back-end de armazenamento compartilhado usado para persistir registros incorporados.
  • thread_id str – Identificador de thread. Se não for fornecido, um UUID será gerado.
  • user_id str – Identificador do usuário associado ao thread. Se for omitido, um UUID é gerado.
  • agent_id str – Identificador do agente associado ao thread. Se for omitido, um UUID é gerado.
  • metadata dict[str, Any] | None – Metadados opcionais semelhantes a JSON associados ao thread.
  • persist_messages_in_config bool – Se _to_config deve incluir instantâneos de mensagens brutas recentes. Definido automaticamente como False para threads que usam o armazenamento do BD para evitar a exportação do conteúdo da tabela de mensagens por meio da configuração do thread.
  • LLM ILlm | None – Adaptador LLM opcional usado para extração de memória e atualizações de resumo de contexto. Quando fornecido, o add_messages extrairá memórias relevantes de cada mensagem adicionada e as armazenará como registros de memória digitados ("memory", "guideline", "fact" ou "preference").
  • memory_extraction_window int - Número de mensagens mais recentes (incluindo a recém-adicionada) para fornecer como contexto ao LLM durante a extração. Defina como -1 para extrair somente uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas. O padrão é -1.
  • context_summary_update_frequency int – Número de mensagens após as quais o resumo do contexto de extração deve ser atualizado. Defina como -1 para resumir apenas uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas. O padrão é -1.
  • memory_extraction_frequency int – Número de mensagens após as quais a extração de memória é acionada. Defina como -1 para extrair somente uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas.
  • memory_extraction_token_limit int – Tamanho máximo, em tokens, dos prompts do LLM usados para extração de memória e execução de atualizações resumidas. Os prompts mais longos são truncados. Se negativo ou 0, o truncamento do prompt será desativado.
  • context_card_token_limit int – Tamanho máximo, em tokens, dos prompts do LLM usados para resumir o cartão de contexto. O padrão é tokens 100_000. Os prompts mais longos são truncados. Se negativo ou 0, o truncamento do prompt será desativado.
  • max_message_token_length int – Tamanho máximo, em tokens, da cópia de tempo imediato de cada mensagem usada durante a extração de memória suportada pelo LLM e atualizações de resumo de contexto. O conteúdo da mensagem armazenada permanece inalterado. Se negativo ou 0, nenhuma redução de tempo imediato é realizada. Se um LLM for fornecido, cópias de prompt grandes serão resumidas em vez de truncadas.
  • message_shortening_input_token_limit int – Tamanho máximo, em tokens, do trecho de mensagem enviado ao LLM ao encurtar cópias de prompt grandes. O padrão é tokens 30_000. Se for negativo ou 0, nenhum limite de saída será aplicado durante a redução baseada em LLM.
  • enable_context_summary bool – Se deve manter um resumo de execução compacto do thread. Quando ativado e fornecido um llm, o resumo é atualizado de acordo com o context_summary_update_frequency. O resumo atual é fornecido como contexto ao extrair memórias.
  • cliente Any | None

Exemplos de

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

Adicione uma entrada de memória manual e indexe-a.

• Parâmetros:
  • content str – Conteúdo de texto a ser armazenado como memória.
  • user_id str – Substituição do identificador de usuário opcional.
  • agent_id str – Substituição do identificador de agente opcional.
  • thread_id str – Substituição de identificador de thread opcional.
  • memory_id str – Identificador estável fornecido pelo chamador opcional para esta linha de memória.
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas para o armazenamento de apoio.
• Retorna: Identificador do registro de memória inserido.
• Tipo de retorno: str

Exemplos de

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

método add_memory_async (assíncrono)

Adicione uma memória de forma assíncrona.

• Parâmetros:
  • content str – Conteúdo na memória a ser armazenado.
  • user_id str – Substituição do escopo do usuário opcional.
  • agent_id str – Substituição do escopo do agente opcional.
  • thread_id str – Substituição de escopo de thread opcional.
  • memory_id str – Identificador de memória fornecido pelo chamador opcional. Quando omitido, as lojas geram um ID.
  • **store_kwargs (Qualquer) – Opções de gravação específicas de implementação encaminhadas para o armazenamento de apoio.
• Tipo de retorno: str

método add_messages

Adicionar mensagens ao tópico e indexá-las.

• Parâmetros:
  • mensagens list[Message | MessageT] – Lista de mensagens a serem anexadas. As mensagens podem ser objetos Message ou dicionários com role e content (e id opcional).
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas para o armazenamento de apoio.
• Retorna: Identificadores de registros de mensagem inseridos.
• Tipo de retorno: list[str]

Exemplos de

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

método add_messages_async (assíncrono)

Adicione mensagens de forma assíncrona ao tópico e indexe-as.

• Parâmetros:
  • mensagens list[Message | MessageT]
  • store_kwargs Any
• Tipo de retorno: list[str]

método delete_memory

Exclua um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) deste thread exato por identificador.

• Parâmetros: memory_id str – Identificador de memória. Somente registros semelhantes à memória (memory, guideline, fact, preference) cujo thread_id armazenado corresponde exatamente a esse thread são excluídos.
• Devoluções: Número de registros excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int

Exemplos de

thread.delete_memory("456")
0

método delete_message

Exclua um registro de mensagem deste thread exato por identificador.

• Parâmetros: message_id str – Identificador de mensagem Somente mensagens cujo thread_id armazenado corresponde exatamente a este thread são excluídas.
• Retorna: Número de registros de mensagem excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int

Observações

A exclusão de uma mensagem remove apenas o registro de mensagem bruta. Memórias derivadas não são excluídas porque as memórias extraídas não persistem por proveniência de mensagem, portanto, elas podem permanecer pesquisáveis ou ainda afetar a saída do cartão de contexto. Use OracleAgentMemory.delete_thread() para excluir o thread junto com suas mensagens e memórias associadas.

Exemplos de

thread.delete_message("123")
0

método get_context_card

Retorna um objeto de cartão de contexto para o thread.

Preferir get_context_card_async quando uma implementação suportada por LLM puder executar E/S de rede remota.

• Parâmetros:
  • fallback_message_count int – Número de mensagens recentes a serem usadas ao derivar o texto de resumo de fallback para recuperação e renderização.
  • max_relevant_results int – Número máximo de registros duráveis recuperados a serem incluídos.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um objeto de cartão de contexto que contém um resumo de contexto de thread com base nas mensagens mais recentes. Use OracleContextCard.content para acessar o texto XML renderizado.
• Tipo da devolução: OracleContextCard

Observações

Isso usa o escopo de pesquisa padrão do thread com exact_thread_match=False, para que memórias relevantes de outros threads para o mesmo usuário/agente possam ser incluídas.

Exemplos de

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

método get_context_card_async (assíncrono)

Retorna assincronicamente um objeto de cartão de contexto para o thread.

• Parâmetros:
  • fallback_message_count int – Número de mensagens recentes a serem usadas ao derivar o texto de resumo de fallback para recuperação e renderização.
  • max_relevant_results int – Número máximo de registros duráveis recuperados a serem incluídos.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um objeto de cartão de contexto para o thread.
• Tipo da devolução: OracleContextCard

método get_messages

Retornar mensagens armazenadas para este tópico.

• Parâmetros:
  • start int | None – Índice de inicialização (com base em 0). Quando omitida junto com end, a janela delimitada mais recente é retornada.
  • end int | None – Índice de término (exclusivo). Quando omitido, uma janela delimitada das mensagens mais recentes é retornada. Informe None ou -1 para solicitar explicitamente todas as mensagens de start em diante.
• Retorna: Mensagens em ordem cronológica.
• Tipo de retorno: list[Mensagem]

Exemplos de

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

método get_messages_async (assíncrono)

Retornar mensagens de tópico brutas de forma assíncrona.

• Parâmetros:
  • start int | None – Índice de início opcional.
  • end int | None – Índice final opcional.
• Retorna: Objetos de mensagem bruta.
• Tipo de retorno: list[Mensagem]

método get_summary

Retorna um resumo do melhor esforço do thread.

Preferir get_summary_async quando uma implementação suportada por LLM puder executar E/S de rede remota.

• Parâmetros:
  • except_last int – Número de mensagens mais recentes a serem excluídas do resumo.
  • token_budget int – Orçamento de token temporário. Quando omitido, um padrão limitado é aplicado. Os valores positivos são truncados somente quando o resumo formatado excede o orçamento, conforme estimado por _estimate_tokens(); o texto retornado é limitado a int(token_budget * 3.5) caracteres. Valores não positivos desativam o limite de saída.
  • **kwargs (Qualquer) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Objeto de resumo que contém o texto de resumo do thread sintetizado.
• Tipo da devolução: OracleSummary

Exemplos de

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

método get_summary_async (assíncrono)

Retorna assincronicamente um resumo do melhor esforço do thread.

• Parâmetros:
  • except_last int – Número de mensagens mais recentes a serem excluídas do resumo.
  • token_budget int – Orçamento de token temporário. Quando omitido, um padrão limitado é aplicado. Os valores positivos são truncados somente quando o resumo formatado excede o orçamento, conforme estimado por _estimate_tokens(); o texto retornado é limitado a int(token_budget * 3.5) caracteres. Valores não positivos desativam o limite de saída.
  • **kwargs (Qualquer um) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Objeto de resumo que contém o texto de resumo do thread sintetizado.
• Tipo da devolução: OracleSummary

método search

Pesquise de forma síncrona registros relevantes para uma consulta.

• Parâmetros:
  • query str – String de consulta em linguagem natural.
  • user_id str | None – Substituição do escopo do usuário opcional. Os valores omitidos herdam o escopo do usuário padrão do thread.
  • agent_id str | None – Substituição do escopo do agente opcional. Os valores omitidos herdam o escopo do agente padrão do thread.
  • thread_id str | None – Substituição de escopo de thread opcional. Os valores omitidos herdam o identificador de thread atual do thread.
  • exact_user_match bool – Se a correspondência do usuário deve ser rigorosa.
  • exact_agent_match bool – Se a correspondência de agente deve ser rigorosa.
  • exact_thread_match bool – Se a correspondência de threads deve ser rigorosa.
  • max_results int – Número máxima opcional de resultados a retornar. Quando fornecido, deve ser pelo menos 1. A omissão desse argumento usa o valor padrão de 10.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory" ou "message".
  • escopo SearchScope – Escopo de pesquisa pré-criado opcional. Forneça scope ou o identificador explícito e os argumentos de correspondência exata, não ambos.
• Devoluções: resultados da pesquisa ordenados por relevância decrescente.
• Tipo de retorno: list[SearchResult]
• Gera: ValueError – Se scope for combinado com identificador explícito ou argumentos de correspondência exata, ou se max_results for menor que 1.

Observações

Os campos de escopo omitidos herdam o escopo de pesquisa padrão deste thread: correspondência exata de usuário e agente mais o user_id, agent_id e thread_id atuais deste thread. A pesquisa de thread padrão sai intencionalmente de exact_thread_match=False, para que possa retornar registros relevantes de outros threads para o mesmo usuário/agente. Informe exact_thread_match=True para restringir os resultados ao thread atual. Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas aos valores None armazenados.

Os valores max_results explícitos devem ser pelo menos 1; a omissão do argumento usa o valor padrão de 10.

método search_async (assíncrono)

Pesquise registros relevantes para uma consulta de forma assíncrona.

• Parâmetros:
  • query str – String de consulta em linguagem natural.
  • user_id str | None – Substituição do escopo do usuário opcional. Os valores omitidos herdam o escopo do usuário padrão do thread.
  • agent_id str | None – Substituição do escopo do agente opcional. Os valores omitidos herdam o escopo do agente padrão do thread.
  • thread_id str | None – Substituição de escopo de thread opcional. Os valores omitidos herdam o identificador de thread atual do thread.
  • exact_user_match bool – Se a correspondência do usuário deve ser rigorosa.
  • exact_agent_match bool – Se a correspondência de agente deve ser rigorosa.
  • exact_thread_match bool – Se a correspondência de threads deve ser rigorosa.
  • max_results int – Número máxima opcional de resultados a retornar. Quando fornecido, deve ser pelo menos 1. A omissão desse argumento usa o valor padrão de 10.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory" ou "message".
  • escopo SearchScope – Escopo de pesquisa pré-criado opcional. Forneça scope ou o identificador explícito e os argumentos de correspondência exata, não ambos.
• Devoluções: resultados da pesquisa ordenados por relevância decrescente.
• Tipo de retorno: list[SearchResult]
• Gera: ValueError – Se scope for combinado com identificador explícito ou argumentos de correspondência exata, ou se max_results for menor que 1.

Observações

Os campos de escopo omitidos herdam o escopo de pesquisa padrão deste thread: correspondência exata de usuário e agente mais o user_id, agent_id e thread_id atuais deste thread. A pesquisa de thread padrão sai intencionalmente de exact_thread_match=False, para que possa retornar registros relevantes de outros threads para o mesmo usuário/agente. Informe exact_thread_match=True para restringir os resultados ao thread atual. Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas aos valores None armazenados.

Os valores max_results explícitos devem ser pelo menos 1; a omissão do argumento usa o valor padrão de 10.

Observação: delete_message() exclui somente a linha de mensagem bruta. Memórias derivadas podem ainda ser pesquisáveis ou aparecer em cartões de contexto. Use OracleAgentMemory.delete_thread() para excluir o thread junto com suas mensagens e memórias associadas.

Mensagens

classe oracleagentmemory.apis.thread.Message

Bases: object

• Parâmetros:
  • função str
  • conteúdo str
  • marcador de data/hora str | None
  • metadados dict[str, Any] | None
  • id str | None

Cartões de Contexto

classe oracleagentmemory.apis.contextcard.ContextCard

Bases: ABC

Objeto de cartão de contexto abstrato retornado por APIs de thread.

propriedade content (abstrato)

• Tipo de Retorno: str
• Descrição: Retorna o texto do cartão de contexto renderizado.

classe oracleagentmemory.core.contextcard.OracleContextCard

Bases: ContextCard

Cartão de contexto retornado por um thread Oracle.

• Parâmetros:
  • resumo str – Texto resumido incorporado ao cartão.
  • tópicos Sequence[str] | None – Tópicos de recuperação opcionais associados ao thread.
  • relevant_results Sequence[SearchResult] | None – Registros duráveis recuperados opcionais incluídos no cartão.
  • recent_messages Sequence[Message] | None – Mensagens brutas recentes opcionais renderizadas no cartão.
  • message_format str – Modelo interno usado ao renderizar recent_messages.

propriedade content

• Tipo de Retorno: str

• Descrição: Retorna o texto do cartão de contexto renderizado.

• Retorna: Texto de cartão de contexto renderizado semelhante a XML adequado para montagem de prompt.
• Tipo de retorno: str

Exemplos de

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

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna o texto do cartão de contexto renderizado usado em fluxos de criação de prompt.

• Retorna: texto de cartão de contexto renderizado semelhante a XML.
• Tipo de retorno: str

Exemplos de

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

Resumos

classe oracleagentmemory.apis.summary.Summary

Bases: ABC

Objeto de resumo de thread resumido retornado por APIs de thread.

propriedade content (abstrato)

• Tipo de Retorno: str
• Descrição: Retorna o texto de resumo sintetizado.

classe oracleagentmemory.core.summary.OracleSummary

Bases: Summary

Resumo retornado por um thread Oracle.

• Parâmetros: content str – Texto de resumo sintetizado a partir da transcrição do thread.

Exemplos de

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

propriedade content

• Tipo de Retorno: str

• Descrição: Retorna o texto resumido sintetizado.

• Retorna: Texto de resumo do thread.
• Tipo de retorno: str

Exemplos de

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

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna o texto resumido renderizado usado em fluxos de criação de prompt.

• Retorna: Texto de resumo renderizado.
• Tipo de retorno: str

Exemplos de

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