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.
  • 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_type="memory".
  • 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. Impostare su -1 per riepilogare solo una volta per chiamata add_messages utilizzando il batch completo dei nuovi messaggi aggiunti. La stessa cadenza viene riutilizzata per l'aggiornamento dei metadati di riepilogo dei thread durante le scritture di trascrizione.
  • 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 utilizzati nell'estrazione della memoria. I prompt più lunghi verranno troncati. Se negativo o 0, non viene eseguito alcun troncamento.
  • 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

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

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

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

• Parametri: memory_id str – identificativo della memoria. Vengono eliminati solo i ricordi 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 eliminati (0 o 1). Restituisce 0 se l'identificativo non esiste o appartiene a un thread diverso.
• Tipo restituito: int.

Note

L'eliminazione riuscita cancella lo stato thread-summary derivato in modo che le chiamate di riepilogo e scheda contesto successive vengano rigenerate dalla trascrizione rimanente. Le memorie derivate non vengono eliminate automaticamente perché le memorie estratte attualmente non persistono per provenienza messaggio.

Esempi

thread.delete_message("123")
0

metodo get_context_card

Restituisce una scheda di contesto simile a XML 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: una scheda contenente un riepilogo del contesto thread basato sui messaggi più recenti.
• Tipo restituito: str

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

metodo get_context_card_async (asincrono)

Restituisce in modo asincrono una scheda di contesto simile a XML 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: una scheda contenente un riepilogo del contesto thread basato sui messaggi più recenti.
• Tipo restituito: str

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_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: un messaggio dell'assistente contenente il riepilogo o un elenco vuoto se il thread non ha messaggi.
• Tipo restituito: list[Messaggio]

Esempi

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
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: un messaggio dell'assistente contenente il riepilogo o un elenco vuoto se il thread non ha messaggi.
• Tipo restituito: list[Messaggio]

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