Thread

Questa pagina presenta l'handle di thread Oracle concreto insieme al tipo di applicazione di supporto messaggi rivolto agli sviluppatori.

Thread Oracle

classe oracleagentmemory.core.OracleThread

Basi: IThread

Thread supportato da un negozio Oracle.

Questa implementazione incorpora e memorizza sia i messaggi thread che le memorie aggiunte manualmente, quindi supporta la ricerca di somiglianza su tutti i record memorizzati.

Note

• I messaggi vengono memorizzati come singoli record (un record per messaggio).
• La ricerca può essere limitata al thread corrente oppure può restituire i risultati da qualsiasi thread (controllato dal client).

Crea un nuovo handle di thread.

• Parametri:
  • store OracleMemoryStore: backend dell'area di memorizzazione condivisa utilizzato per rendere persistenti i record incorporati.
  • thread_id str: identificativo del thread. Se non viene fornito, viene generato un UUID.
  • user_id str: identificativo utente associato al thread. Se omesso, viene generato un UUID.
  • agent_id str: identificativo dell'agente associato al thread. Se omesso, viene generato un UUID.
  • metadati dict[str, Any] | None: metadati facoltativi simili a JSON associati al thread.
  • persist_messages_in_config bool: indica se _to_config deve includere snapshot di messaggi raw recenti. Impostato automaticamente su False per i thread che utilizzano l'area di memorizzazione DB per evitare l'esportazione dei contenuti della tabella messaggi tramite la configurazione dei thread.
  • LLM ILlm | None: adattatore LLM opzionale utilizzato per l'estrazione della memoria e gli aggiornamenti di riepilogo del contesto. Se fornito, add_messages estrae le memorie pertinenti da ogni messaggio aggiunto e le memorizza come record di memoria digitata ("memory", "guideline", "fact" o "preference").
  • memory_extraction_window int: numero di messaggi più recenti (incluso quello appena aggiunto) da fornire come contesto per l'LLM durante l'estrazione. Impostare su -1 per estrarre una sola volta ogni chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. L'impostazione predefinita è -1.
  • context_summary_update_frequency int: numero di messaggi al termine dei quali aggiornare il riepilogo del contesto di estrazione. Impostare su -1 per riepilogare solo una volta per chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. L'impostazione predefinita è -1.
  • memory_extraction_frequency int: numero di messaggi al termine dei quali viene attivata l'estrazione della memoria. Impostare su -1 per estrarre una sola volta ogni chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti.
  • memory_extraction_token_limit int: dimensione massima, nei token, dei prompt LLM utilizzati per l'estrazione della memoria e l'esecuzione di aggiornamenti di riepilogo. I prompt più lunghi vengono troncati. Se negativo o 0, il troncamento dei prompt è disabilitato.
  • context_card_token_limit int: dimensione massima, in token, dei prompt LLM utilizzati per il riepilogo delle schede di contesto. L'impostazione predefinita è Token 100_000. I prompt più lunghi vengono troncati. Se negativo o 0, il troncamento dei prompt è disabilitato.
  • max_message_token_length int: dimensione massima, nei token, della copia in fase di prompt di ogni messaggio utilizzato durante l'estrazione della memoria supportata da LLM e gli aggiornamenti di riepilogo del contesto. Il contenuto del messaggio memorizzato rimane invariato. Se negativo o 0, non viene eseguito alcun accorciamento rapido. Se viene fornito un LLM, le copie prompt di grandi dimensioni vengono riepilogate anziché troncate.
  • message_shortening_input_token_limit int: la dimensione massima, nei token, dell'estratto del messaggio inviato all'LLM quando si accorciano le copie dei prompt di dimensioni eccessive. L'impostazione predefinita è Token 30_000. Se negativo o 0, durante l'accorciamento basato su LLM non viene applicato alcun limite in uscita.
  • enable_context_summary bool – Indica se mantenere un riepilogo sull'esecuzione compatto del thread. Se abilitato e viene fornito un valore llm, il riepilogo viene aggiornato in base all'indirizzo context_summary_update_frequency. Il riepilogo corrente viene fornito come contesto durante l'estrazione delle memorie.
  • client Any | None

Esempi

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

metodo add_memory

Aggiungere una voce di memoria manuale e indicizzarla.

• Parametri:
  • content str: contenuto di testo da memorizzare come memoria.
  • user_id str: sostituzione facoltativa dell'identificativo utente.
  • agent_id str: sostituzione facoltativa dell'identificativo dell'agente.
  • thread_id str: sostituzione facoltativa dell'identificativo del thread.
  • memory_id str: identificativo stabile fornito dal chiamante opzionale per questa riga di memoria.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'area di memorizzazione inoltrate al backing store.
• Restituzioni: identificativo del record di memoria inserito.
• Tipo restituito: str

Esempi

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

metodo add_memory_async (asincrono)

Aggiungere una memoria in modo asincrono.

• Parametri:
  • content str: contenuto di memoria da memorizzare.
  • user_id str: sostituzione facoltativa dell'ambito utente.
  • agent_id str: sostituzione facoltativa dell'ambito dell'agente.
  • thread_id str: sostituzione facoltativa dell'ambito del thread.
  • memory_id str: identificativo di memoria fornito dal chiamante opzionale. Se omesso, i negozi generano un ID.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al backing store.
• Tipo restituito: str

metodo add_messages

Aggiungere i messaggi al thread e indicizzarli.

• Parametri:
  • messaggi list[Message | MessageT]: elenco di messaggi da aggiungere. I messaggi possono essere oggetti o dizionari Message con role e content (e facoltativi id).
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'area di memorizzazione inoltrate al backing store.
• Restituzioni: identificativi dei record messaggio inseriti.
• Tipo restituito: list[str]

Esempi

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

metodo add_messages_async (asincrono)

Aggiungere i messaggi al thread in modo asincrono e indicizzarli.

• Parametri:
  • messaggi list[Message | MessageT]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo delete_memory

Elimina un record simile alla memoria (ad esempio, una memoria, un fatto, una preferenza o una linea guida) da questo thread esatto per identificativo.

• Parametri: memory_id str – identificativo della memoria. Vengono eliminati solo i record di tipo memoria (memory, guideline, fact, preference) il cui thread_id memorizzato corrisponde esattamente a questo thread.
• Restituzioni: numero di record eliminati (0 o 1). Restituisce 0 se l'identificativo non esiste o appartiene a un thread diverso.
• Tipo restituito: int.

Esempi

thread.delete_memory("456")
0

metodo delete_message

Eliminare un record messaggio da questo thread esatto in base all'identificativo.

• Parametri: message_id str: identificativo del messaggio. Vengono eliminati solo i messaggi il cui thread_id memorizzato corrisponde esattamente a questo thread.
• Restituzioni: numero di record messaggio eliminati (0 o 1). Restituisce 0 se l'identificativo non esiste o appartiene a un thread diverso.
• Tipo restituito: int.

Note

L'eliminazione di un messaggio comporta la rimozione solo del record di messaggio raw. Le memorie derivate non vengono eliminate perché le memorie estratte non persistono per provenienza messaggio, quindi potrebbero rimanere ricercabili o influenzare ancora l'output della scheda contesto. Utilizzare OracleAgentMemory.delete_thread() per eliminare il thread insieme ai messaggi e alle memorie associati.

Esempi

thread.delete_message("123")
0

metodo get_context_card

Restituisce un oggetto context-card per il thread.

Preferire get_context_card_async quando un'implementazione supportata da LLM può eseguire I/O di rete remota.

• Parametri:
  • fallback_message_count int: numero di messaggi recenti da utilizzare per derivare il testo di riepilogo di fallback per il recupero e il rendering.
  • max_relevant_results int: numero massimo di record permanenti recuperati da includere.
  • max_recent_messages int: numero massimo di messaggi raw finali da incorporare parola per parola.
  • **kwargs (Qualsiasi): riservato per le future opzioni di scheda contesto. Gli argomenti delle parole chiave inattesi generano TypeError.
• Restituzioni: un oggetto di scheda contesto contenente un riepilogo del contesto thread basato sui messaggi più recenti. Utilizzare OracleContextCard.content per accedere al testo di tipo XML visualizzato.
• Tipo restituito: OracleContextCard

Note

Questo utilizza l'ambito di ricerca predefinito del thread con exact_thread_match=False, quindi è possibile includere memorie rilevanti da altri thread per lo stesso utente/agente.

Esempi

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

metodo get_context_card_async (asincrono)

Restituisce in modo asincrono un oggetto context-card per il thread.

• Parametri:
  • fallback_message_count int: numero di messaggi recenti da utilizzare per derivare il testo di riepilogo di fallback per il recupero e il rendering.
  • max_relevant_results int: numero massimo di record permanenti recuperati da includere.
  • max_recent_messages int: numero massimo di messaggi raw finali da incorporare parola per parola.
  • **kwargs (Qualsiasi): riservato per le future opzioni di scheda contesto. Gli argomenti delle parole chiave inattesi generano TypeError.
• Restituzioni: un oggetto di scheda contesto per il thread.
• Tipo restituito: OracleContextCard

metodo get_messages

Restituire salvati i messaggi per questa discussione.

• Parametri:
  • start int | None – Indice di avvio (basato su 0). Se omesso insieme a end, viene restituita la finestra con limite più recente.
  • end int | None – Indice finale (escluso). Se omesso, viene restituita una finestra delimitata dei messaggi più recenti. Passare None o -1 per richiedere in modo esplicito tutti i messaggi da start in poi.
• Restituzioni: messaggi in ordine cronologico.
• Tipo restituito: list[Messaggio]

Esempi

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

metodo get_messages_async (asincrono)

Restituisce i messaggi raw thread in modo asincrono.

• Parametri:
  • start int | None: indice di avvio opzionale.
  • end int | None: indice finale facoltativo.
• Restituzioni: oggetti messaggio raw.
• Tipo restituito: list[Messaggio]

metodo get_summary

Restituisce un riepilogo del thread con il miglior sforzo.

Preferire get_summary_async quando un'implementazione supportata da LLM può eseguire I/O di rete remota.

• Parametri:
  • except_last int: numero di messaggi più recenti da escludere dal riepilogo.
  • token_budget int: budget token temporaneo. Se omesso, viene applicato un valore predefinito limitato. I valori positivi vengono troncati solo quando il sintetico formattato supera il budget come stimato da _estimate_tokens(); il testo restituito viene quindi limitato a int(token_budget * 3.5) caratteri. I valori non positivi disabilitano il limite di output.
  • **kwarg (Qualsiasi): riservato per opzioni di riepilogo future. Gli argomenti delle parole chiave inattesi generano TypeError.
• Restituzioni: oggetto di riepilogo contenente il testo di riepilogo del thread sintetizzato.
• Tipo restituito: OracleSummary

Esempi

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

metodo get_summary_async (asincrono)

Restituisce in modo asincrono un riepilogo del miglior sforzo del thread.

• Parametri:
  • except_last int: numero di messaggi più recenti da escludere dal riepilogo.
  • token_budget int: budget token temporaneo. Se omesso, viene applicato un valore predefinito limitato. I valori positivi vengono troncati solo quando il sintetico formattato supera il budget come stimato da _estimate_tokens(); il testo restituito viene quindi limitato a int(token_budget * 3.5) caratteri. I valori non positivi disabilitano il limite di output.
  • **kwarg (Qualsiasi): riservato per opzioni di riepilogo future. Gli argomenti delle parole chiave inattesi generano TypeError.
• Restituzioni: oggetto di riepilogo contenente il testo di riepilogo del thread sintetizzato.
• Tipo restituito: OracleSummary

metodo search

Cercare in modo sincrono i record pertinenti a un'interrogazione.

• Parametri:
  • query str: stringa di query in linguaggio naturale.
  • user_id str | None: sostituzione facoltativa dell'ambito utente. I valori omessi ereditano l'ambito utente predefinito del thread.
  • agent_id str | None: sostituzione facoltativa dell'ambito dell'agente. I valori omessi ereditano l'ambito agente predefinito del thread.
  • thread_id str | None: sostituzione facoltativa dell'ambito del thread. I valori omessi ereditano l'identificativo thread corrente del thread.
  • exact_user_match bool: indica se la corrispondenza degli utenti deve essere rigorosa.
  • exact_agent_match bool: indica se la corrispondenza degli agenti deve essere rigorosa.
  • exact_thread_match bool: indica se la corrispondenza dei thread deve essere rigorosa.
  • max_results int: numero massimo facoltativo di risultati da restituire. Se fornito, deve essere almeno 1. Se si omette questo argomento, viene utilizzato il valore predefinito 10.
  • record_types list[str]: elenco facoltativo di tipi di record da includere, ad esempio "memory" o "message".
  • ambito SearchScope: ambito di ricerca predefinito facoltativo. Fornire scope o l'identificativo esplicito e gli argomenti di corrispondenza esatta, non entrambi.
• Restituzioni: risultati della ricerca ordinati in base alla minore rilevanza.
• Tipo restituito: list[SearchResult]
• Aumenti: ValueError: se scope viene combinato con un identificativo esplicito o con argomenti di corrispondenza esatta oppure se max_results è minore di 1.

Note

I campi di ambito omessi ereditano l'ambito di ricerca predefinito di questo thread: l'esatta corrispondenza di utente e agente più gli attuali user_id, agent_id e thread_id di questo thread. La ricerca thread predefinita lascia intenzionalmente exact_thread_match=False, quindi potrebbe restituire record pertinenti da altri thread per lo stesso utente/agente. Passare exact_thread_match=True per limitare i risultati al thread corrente. I valori espliciti dell'ambito None seguono comunque le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai valori None memorizzati.

I valori max_results espliciti devono essere almeno 1. Se si omette l'argomento, verrà utilizzato il valore predefinito 10.

metodo search_async (asincrono)

Cercare in modo asincrono i record pertinenti a un'interrogazione.

• Parametri:
  • query str: stringa di query in linguaggio naturale.
  • user_id str | None: sostituzione facoltativa dell'ambito utente. I valori omessi ereditano l'ambito utente predefinito del thread.
  • agent_id str | None: sostituzione facoltativa dell'ambito dell'agente. I valori omessi ereditano l'ambito agente predefinito del thread.
  • thread_id str | None: sostituzione facoltativa dell'ambito del thread. I valori omessi ereditano l'identificativo thread corrente del thread.
  • exact_user_match bool: indica se la corrispondenza degli utenti deve essere rigorosa.
  • exact_agent_match bool: indica se la corrispondenza degli agenti deve essere rigorosa.
  • exact_thread_match bool: indica se la corrispondenza dei thread deve essere rigorosa.
  • max_results int: numero massimo facoltativo di risultati da restituire. Se fornito, deve essere almeno 1. Se si omette questo argomento, viene utilizzato il valore predefinito 10.
  • record_types list[str]: elenco facoltativo di tipi di record da includere, ad esempio "memory" o "message".
  • ambito SearchScope: ambito di ricerca predefinito facoltativo. Fornire scope o l'identificativo esplicito e gli argomenti di corrispondenza esatta, non entrambi.
• Restituzioni: risultati della ricerca ordinati in base alla minore rilevanza.
• Tipo restituito: list[SearchResult]
• Aumenti: ValueError: se scope viene combinato con un identificativo esplicito o con argomenti di corrispondenza esatta oppure se max_results è minore di 1.

Note

I campi di ambito omessi ereditano l'ambito di ricerca predefinito di questo thread: l'esatta corrispondenza di utente e agente più gli attuali user_id, agent_id e thread_id di questo thread. La ricerca thread predefinita lascia intenzionalmente exact_thread_match=False, quindi potrebbe restituire record pertinenti da altri thread per lo stesso utente/agente. Passare exact_thread_match=True per limitare i risultati al thread corrente. I valori espliciti dell'ambito None seguono comunque le regole di corrispondenza esatta risolte: exact_*_match=False lascia la dimensione non vincolata, mentre exact_*_match=True corrisponde solo ai valori None memorizzati.

I valori max_results espliciti devono essere almeno 1. Se si omette l'argomento, verrà utilizzato il valore predefinito 10.

Nota: delete_message() elimina solo la riga del messaggio raw. I ricordi derivati possono ancora essere ricercabili o apparire nelle schede contesto. Utilizzare OracleAgentMemory.delete_thread() per eliminare il thread insieme ai messaggi e alle memorie associati.

Messaggi

classe oracleagentmemory.apis.thread.Message

Basi: object

• Parametri:
  • ruolo str
  • contenuto str
  • indicatore orario str | None
  • metadati dict[str, Any] | None
  • ID str | None

Schede contesto

classe oracleagentmemory.apis.contextcard.ContextCard

Basi: ABC

Oggetto context-card astratto restituito dalle API thread.

proprietà content (abstract)

• Tipo restituito: str
• Descrizione: restituisce il testo della scheda contesto visualizzata.

classe oracleagentmemory.core.contextcard.OracleContextCard

Basi: ContextCard

Scheda contesto restituita da un thread Oracle.

• Parametri:
  • summary str: testo di riepilogo incorporato nella scheda.
  • argomenti Sequence[str] | None: argomenti di recupero facoltativi associati al thread.
  • relevant_results Sequence[SearchResult] | None: record permanenti recuperati facoltativi inclusi nella scheda.
  • recent_messages Sequence[Message] | None: messaggi raw recenti facoltativi visualizzati nella scheda.
  • message_format str: modello interno utilizzato per il rendering di recent_messages.

proprietà content

• Tipo restituito: str

• Descrizione: restituisce il testo della scheda contesto visualizzata.

• Restituzioni: testo della scheda di contesto visualizzato in formato XML adatto per l'assemblaggio dei prompt.
• Tipo restituito: str

Esempi

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

proprietà formatted_content

• Tipo restituito: str

• Descrizione: restituisce il testo della scheda contesto visualizzato utilizzato nei flussi di generazione prompt.

• Restituzioni: testo della scheda di contesto visualizzato in formato XML.
• Tipo restituito: str

Esempi

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

Riepiloghi

classe oracleagentmemory.apis.summary.Summary

Basi: ABC

Oggetto thread-summary astratto restituito dalle API thread.

proprietà content (abstract)

• Tipo restituito: str
• Descrizione: restituisce il testo sintetico del sintetico.

classe oracleagentmemory.core.summary.OracleSummary

Basi: Summary

Riepilogo restituito da un thread Oracle.

• Parametri: content str: testo di riepilogo sintetizzato dalla trascrizione del thread.

Esempi

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

proprietà content

• Tipo restituito: str

• Descrizione: restituisce il testo di riepilogo sintetizzato.

• Restituzioni: testo di riepilogo per il thread.
• Tipo restituito: str

Esempi

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

proprietà formatted_content

• Tipo restituito: str

• Descrizione: restituisce il testo di riepilogo visualizzato utilizzato nei flussi di generazione prompt.

• Restituzioni: testo sintetico visualizzato.
• Tipo restituito: str

Esempi

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