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).

Creare una nuova istanza di OracleThread.

• 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_config MemoryExtractionConfig: configurazione opzionale di estrazione della memoria a livello di thread. Usalo per controllare le impostazioni di estrazione automatica come la modalità di estrazione, il comportamento di riepilogo, i limiti di estrazione e se l'estrazione automatica è abilitata. Passare questa configurazione raggruppata o i parametri di estrazione in linea non più validi, non entrambi. Se omesso, OracleThread() standalone utilizza le impostazioni predefinite SDK per i campi di estrazione e mantiene abilitati i riepiloghi di contesto.

  • memory_extraction_window int –

    Numero di messaggi più recenti (incluso quello appena aggiunto) da fornire come contesto al 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.

    Non più valida

    Deprecato dalla versione 26.6.0: questo parametro è deprecato nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • context_summary_update_frequency int –

    Numero di messaggi dopo i quali deve essere aggiornato 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.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • frequenza_estrazione_memoria 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.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • memory_extraction_token_limit int –

    Dimensione massima, in 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.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • context_card_token_limit int: budget token di input massimo per il prompt LLM utilizzato per creare l'elenco di riepilogo e argomenti inclusi nella scheda contesto. Il valore predefinito è 100_000; il valore è minore o uguale a 0. Disabilita troncamento prompt.
  • context_card_type_search_concurrency int: numero massimo di ricerche di record simili alla memoria da eseguire contemporaneamente durante la creazione di una scheda di contesto con min_relevant_results_by_type. L'impostazione predefinita è 5.
  • 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 tempestivo. 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 di 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. Il valore predefinito è True per OracleThread() standalone.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • memory_extraction_custom_instructions str | None –

    Istruzioni personalizzate facoltative aggiunte al prompt del sistema di estrazione automatica della memoria per questo thread.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • memory_extraction_inherit_message_metadata bool | Sequence[str] –

    Indica se le memorie estratte automaticamente ereditano metadati dai messaggi di origine. Passare True per ereditare tutti i metadati del messaggio, una sequenza non stringa di chiavi di metadati del messaggio di livello superiore per ereditare solo tali chiavi o False per disabilitare l'ereditarietà. L'impostazione predefinita è True. Se un passaggio di estrazione utilizza più messaggi di origine, i metadati selezionati devono corrispondere tra tali messaggi.

    Informazioni: non più valido dalla versione 26.6.0: questo parametro non è più valido nella versione 26.6.0 e verrà rimosso nella versione 27.1. Utilizzare invece memory_extraction_config.

  • client OracleAgentMemory | None

Esempi

from oracleagentmemory.core import OracleAgentMemory
import oracledb
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,
    memory_extraction_config=MemoryExtractionConfig(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.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker: categoria di memoria da memorizzare. I valori supportati sono "memory", "fact", "guideline" e "preference". Se omesso, il contenuto viene memorizzato come "memory" generale.
  • 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.
  • metadati dict[str, Any] | None: metadati facoltativi da rendere persistenti con la memoria memorizzata.
  • timestamp str | None: indicatore orario facoltativo da salvare sulla memoria. Rappresenta quando è stata creata la memoria. Se omesso o None, il negozio utilizza l'ora corrente. Se ttl_anchor è TimeToLiveAnchor.TIMESTAMP, fornire un valore di indicatore orario ISO-8601 concreto. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • ttl_days int | None: durata Time To Live opzionale in giorni. Omettere questo argomento per utilizzare la durata Time To Live predefinita dello schema. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per memorizzare una memoria non in scadenza quando non lo è. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del database o TimeToLiveAnchor.TIMESTAMP per l'indicatore orario della memoria. La scadenza ancorata all'indicatore orario richiede un indicatore orario ISO-8601 concreto per questa memoria. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • **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.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker: categoria di memoria da memorizzare. I valori supportati sono "memory", "fact", "guideline" e "preference". Se omesso, il contenuto viene memorizzato come "memory" generale.
  • 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.
  • metadati dict[str, Any] | None: metadati facoltativi da rendere persistenti con la memoria memorizzata.
  • timestamp str | None: indicatore orario facoltativo da salvare sulla memoria. Rappresenta quando è stata creata la memoria. Se omesso o None, il negozio utilizza l'ora corrente.
  • ttl_days int | None: durata Time To Live opzionale in giorni. Omettere questo argomento per utilizzare la durata Time To Live predefinita dello schema oppure passare None per una memoria che non scade.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale. Utilizzare TimeToLiveAnchor.CREATED_AT o TimeToLiveAnchor.TIMESTAMP.
  • **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.

In modalità estrazione in background, questo metodo viene restituito dopo l'inserimento dei messaggi raw e l'estrazione in background dovuta viene tentata in background.

• Parametri:
  • messaggi list[Message | MessageT]: elenco di messaggi da aggiungere. I messaggi possono essere oggetti Message o dizionari con role e content (e facoltativo id).
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]: metadati condivisi o per messaggio facoltativi per rendere persistenti. Se omesso, vengono utilizzati i metadati incorporati in ogni messaggio.
  • ttl_days int | None | list[int | None]: durata Time To Live facoltativa in giorni per i messaggi aggiunti. Omettere questo argomento per utilizzare la durata Time To Live predefinita dello schema. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per creare messaggi non in scadenza quando non lo è. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. I valori scalari vengono applicati al batch completo.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: ancoraggio Time To Live opzionale. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del database o TimeToLiveAnchor.TIMESTAMP per ogni indicatore orario del messaggio. La scadenza ancorata all'indicatore orario richiede un indicatore orario ISO-8601 concreto per ogni messaggio interessato. Se omesso, i messaggi scadono in relazione a TimeToLiveAnchor.CREATED_AT. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'area di memorizzazione inoltrate al backing store.
• Restituzioni: identificativi dei record messaggio inseriti. In modalità di estrazione in background, il lavoro di estrazione automatica potrebbe essere ancora in esecuzione quando vengono restituiti questi identificatori.
• Tipo restituito: list[str]

Note

In MemoryExtractionMode.BACKGROUND, i messaggi raw vengono mantenuti prima della memorizzazione delle memorie estratte. Se l'estrazione in background non fa la coda, o se un'attesa di capacità di coda configurata raggiunge il suo timeout, i messaggi non elaborati inseriti rimangono memorizzati e la chiamata continua senza memorie estratte o solleva TimeoutError, a seconda di background_extraction_queue_full_behavior.

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.

In modalità estrazione in background, questo metodo viene restituito dopo l'inserimento dei messaggi raw e l'estrazione in background dovuta viene tentata in background.

In MemoryExtractionMode.BACKGROUND, i messaggi raw vengono mantenuti prima della memorizzazione delle memorie estratte. Se l'estrazione in background non fa la coda, o se un'attesa di capacità di coda configurata raggiunge il suo timeout, i messaggi non elaborati inseriti rimangono memorizzati e la chiamata continua senza memorie estratte o solleva TimeoutError, a seconda di background_extraction_queue_full_behavior.

• Parametri:
  • messaggi list[Message | MessageT]
  • metadati dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • 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 rimuove solo il record del messaggio raw. I ricordi derivati non vengono eliminati perché non vengono ancora tracciati i ricordi estratti da quale messaggio, in modo che possano rimanere ricercabili o influenzare ancora l'output della scheda di 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. Se omesso, viene risolto in 5.
  • max_relevant_results int: numero massimo di record permanenti recuperati da includere. Se omesso, questo si risolve a 5 a meno che non sia fornito min_relevant_results_by_type; in tal caso si risolve al più grande di 5 e alla somma dei minimi per tipo richiesti.
  • max_recent_messages int: numero massimo di messaggi raw finali da incorporare parola per parola. Se omesso, viene risolto in 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker: soglie minime opzionali per tipo per i record di tipo memoria rilevanti inclusi nella scheda di contesto. I tipi richiesti vengono cercati per primi e gli slot max_relevant_results rimanenti vengono compilati da tutti i tipi di record supportati simili alla memoria. Le chiavi supportate sono "memory", "fact", "guideline" e "preference".
  • **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
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
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. Se omesso, viene risolto in 5.
  • max_relevant_results int: numero massimo di record permanenti recuperati da includere. Se omesso, questo si risolve a 5 a meno che non sia fornito min_relevant_results_by_type; in tal caso si risolve al più grande di 5 e alla somma dei minimi per tipo richiesti.
  • max_recent_messages int: numero massimo di messaggi raw finali da incorporare parola per parola. Se omesso, viene risolto in 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker: soglie minime opzionali per tipo per i record di tipo memoria rilevanti inclusi nella scheda di contesto. I tipi richiesti vengono cercati per primi e gli slot max_relevant_results rimanenti vengono compilati da tutti i tipi di record supportati simili alla memoria. Le chiavi supportate sono "memory", "fact", "guideline" e "preference".
  • **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

Esempi

card = await thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
)
len(card.relevant_results or []) <= 5
True

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. La chiamata può restituire meno di max_results se esistono meno record corrispondenti non scaduti.
  • record_types list[str]: elenco facoltativo di tipi di record da includere, ad esempio "memory" o "message".

  • filtro_metadata dict[str, Any] | None:

    Mapping facoltativo del filtro dei metadati utilizzato come filtro aggiuntivo dopo il filtro dell'ambito e del tipo di record. Le voci in metadata_filter sono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati dei record memorizzati. I dizionari nidificati corrispondono in modo ricorsivo agli oggetti metadati nidificati. I valori scalari e di elenco devono corrispondere esattamente; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Omettere questo argomento o passare None per eseguire la ricerca senza filtrare i metadati. Ad esempio, metadata_filter={"source": "chat"} per un campo scalare, metadata_filter={"travel": {"need": "transit"}} per un campo nidificato e metadata_filter={"tags": ["trip", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo. "$array_contains" corrisponde a un valore o a tutti i valori di un elenco. "$array_contains_any" corrisponde ad almeno un valore di un elenco. "$not" nega un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore di corrispondenza esatta raw. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • 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]
• Soluzioni: ValueError: se scope viene combinato con un identificativo esplicito o con argomenti di corrispondenza esatta, se max_results è minore di 1 o se metadata_filter non è né un dizionario né None.

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. Questo è un limite superiore: la chiamata può restituire meno di max_results risultati quando i filtri sono troppo restrittivi, quando esistono meno record corrispondenti o a causa di un funzionamento di ricerca specifico dell'implementazione.

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".

  • filtro_metadata dict[str, Any] | None:

    Mapping facoltativo del filtro dei metadati utilizzato come filtro aggiuntivo dopo il filtro dell'ambito e del tipo di record. Le voci in metadata_filter sono combinate con la semantica AND. Le voci il cui valore non è un dizionario operatore a livello di campo utilizzano la semantica di corrispondenza esatta: la chiave richiesta deve esistere nei metadati dei record memorizzati. I dizionari nidificati corrispondono in modo ricorsivo agli oggetti metadati nidificati. I valori scalari e di elenco devono corrispondere esattamente; anche l'ordine e la lunghezza dell'elenco devono corrispondere. Omettere questo argomento o passare None per eseguire la ricerca senza filtrare i metadati. Ad esempio, metadata_filter={"source": "chat"} per un campo scalare, metadata_filter={"travel": {"need": "transit"}} per un campo nidificato e metadata_filter={"tags": ["trip", "urgent"]} per una corrispondenza esatta dell'elenco. Combina le condizioni per richiederle tutte:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Per eseguire il test dell'appartenenza all'array, utilizzare un dizionario operatore a livello di campo. "$array_contains" corrisponde a un valore o a tutti i valori di un elenco. "$array_contains_any" corrisponde ad almeno un valore di un elenco. "$not" nega un'altra espressione a livello di campo nello stesso campo, incluso un dizionario operatore o un valore di corrispondenza esatta raw. Le espressioni negative corrispondono quando l'espressione positiva non riesce, inclusi i campi mancanti; l'appartenenza all'array negata corrisponde anche ai campi non array:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • 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]
• Soluzioni: ValueError: se scope viene combinato con un identificativo esplicito o con argomenti di corrispondenza esatta, se max_results è minore di 1 o se metadata_filter non è né un dizionario né None.

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. Questo è un limite superiore: la chiamata può restituire meno di max_results risultati quando i filtri sono troppo restrittivi, quando esistono meno record corrispondenti o a causa di un funzionamento di ricerca specifico dell'implementazione.

metodo update_memory

Aggiorna un record simile alla memoria di proprietà di questo thread.

• Parametri:
  • memory_id str – Identificativo di memoria. Vengono aggiornati solo i record di tipo memoria (memory, guideline, fact, preference) il cui thread_id memorizzato corrisponde esattamente a questo thread.
  • content str: contenuto sostitutivo opzionale. Fornire una stringa per sostituire il contenuto memorizzato. Se omesso, il contenuto memorizzato viene conservato. Il passaggio di None non è supportato; omettere content per mantenere il valore corrente oppure utilizzare delete_memory() per rimuovere il record.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Se omesso, i metadati memorizzati vengono conservati. Se fornita, sostituisce l'oggetto metadati memorizzato. Questa API non unisce in modo approfondito i metadati.
  • timestamp str | None: nuovo indicatore orario facoltativo per questa memoria. Rappresenta quando è stata creata la memoria. Se omesso, l'indicatore orario memorizzato viene conservato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di creazione del record nel negozio. Se ttl_anchor è TimeToLiveAnchor.TIMESTAMP, gli indicatori orari di sostituzione devono essere stringhe ISO-8601. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento per lasciare invariata la scadenza corrente a meno che non venga specificato ttl_anchor. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per cancellare la scadenza quando non è impostata. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. Le memorie scadute non sono disponibili per questa API thread e non possono essere aggiornate.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione della memoria o TimeToLiveAnchor.TIMESTAMP per la sostituzione timestamp fornita nello stesso aggiornamento oppure l'indicatore orario dell'evento memorizzato quando timestamp viene omesso. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, il thread utilizza TimeToLiveAnchor.CREATED_AT. Gli aggiornamenti con indicatore orario basato su indicatore orario richiedono un indicatore orario ISO-8601 sostitutivo nella stessa chiamata o un indicatore orario evento memorizzato esistente in tale formato. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • **kwargs (Qualsiasi) – gli argomenti con parole chiave impreviste vengono rifiutati.
• Restituzioni: identificativo del record aggiornato simile alla memoria.
• Tipo restituito: str

metodo update_memory_async (asincrono)

Aggiorna un record simile alla memoria in modo asincrono.

• Parametri:
  • memory_id str: identificativo del record simile alla memoria da aggiornare.
  • content str: contenuto sostitutivo opzionale. Fornire una stringa per sostituire il contenuto memorizzato. Se omesso, il contenuto memorizzato viene conservato. Il passaggio di None non è supportato; omettere content per mantenere il valore corrente oppure utilizzare delete_memory() per rimuovere il record.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Se omesso, i metadati memorizzati vengono conservati. Se fornita, sostituisce l'oggetto metadati memorizzato. Questa API non unisce in modo approfondito i metadati.
  • timestamp str | None: nuovo indicatore orario facoltativo per questa memoria. Rappresenta quando è stata creata la memoria. Se omesso, l'indicatore orario memorizzato viene conservato. Passare None per cancellare l'indicatore orario salvato e utilizzare l'ora di creazione del record nel negozio.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento insieme a ttl_anchor per conservare l'indicatore orario di scadenza corrente. Passare None per cancellare la scadenza.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dello schema.
  • **kwargs (Qualsiasi) – gli argomenti con parole chiave impreviste vengono rifiutati.
• Restituzioni: identificativo del record aggiornato simile alla memoria.
• Tipo restituito: str

Esempi

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

metodo update_message

Aggiornare un record di messaggio raw di proprietà di questo thread esatto.

• Parametri:
  • message_id str: identificativo del messaggio. Vengono aggiornati solo i messaggi il cui thread_id memorizzato corrisponde esattamente a questo thread.
  • content str: contenuto opzionale del messaggio di sostituzione. Fornire una stringa per sostituire il contenuto memorizzato. Se omesso, il contenuto memorizzato viene conservato. Il passaggio di None non è supportato.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Se omesso, i metadati memorizzati vengono conservati. Se fornita, sostituisce l'oggetto metadati memorizzato. Questa API non unisce in modo approfondito i metadati.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento per lasciare invariata la scadenza corrente a meno che non venga specificato ttl_anchor. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per cancellare la scadenza quando non è impostata. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. I messaggi scaduti non sono disponibili per questa API thread e non possono essere aggiornati.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del messaggio o TimeToLiveAnchor.TIMESTAMP per l'indicatore orario dell'evento memorizzato. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dello schema. Quando ttl_anchor viene omesso durante un aggiornamento, il thread utilizza TimeToLiveAnchor.CREATED_AT. Gli aggiornamenti con indicatore orario richiedono un indicatore orario esistente del messaggio ISO-8601 memorizzato. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • **kwargs (Qualsiasi) – gli argomenti con parole chiave impreviste vengono rifiutati.
• Restituzioni: identificativo del record messaggio aggiornato.
• Tipo restituito: str

Note

I campi omessi vengono conservati dal record memorizzato. Il ruolo memorizzato e l'indicatore orario rimangono invariati. La modifica del contenuto aggiorna la cronologia dei messaggi raw e, quando l'estrazione automatica è abilitata, può far sì che l'SDK estragga nuovamente le memorie dal messaggio modificato e dalla cronologia precedente. In modalità INLINE, l'estrazione viene completata prima che venga restituito il metodo. In modalità BACKGROUND, questo metodo viene restituito dopo la riuscita dell'aggiornamento del messaggio raw e l'estrazione in background viene tentata. Questo lavoro di follow-up non influisce sulla normale frequenza di estrazione utilizzata dalle successive chiamate add_messages(). Le memorie estratte esistenti rimangono in vigore mentre le memorie appena estratte dal contenuto modificato possono essere aggiunte. Poiché l'aggiornamento del messaggio raw e qualsiasi scrittura di memoria estratta successiva non si verificano in modo atomico, le memorie estratte possono comunque riflettere il contenuto del messaggio precedente se il lavoro in background non si inserisce nella coda, se un'attesa di capacità di coda configurata raggiunge il timeout o se il lavoro di estrazione successivo non riesce. Inoltre, si noti che le memorie estratte esistenti mantengono la loro scadenza originale quando il TTL di un messaggio di origine cambia.

Esempi

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

metodo update_message_async (asincrono)

Aggiornare un record di messaggio raw di proprietà di questo thread esatto in modo asincrono.

• Parametri:
  • message_id str: identificativo del messaggio. Vengono aggiornati solo i messaggi il cui thread_id memorizzato corrisponde esattamente a questo thread.
  • content str: contenuto opzionale del messaggio di sostituzione. Fornire una stringa per sostituire il contenuto memorizzato. Se omesso, il contenuto memorizzato viene conservato. Il passaggio di None non è supportato.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Se omesso, i metadati memorizzati vengono conservati. Se fornita, sostituisce l'oggetto metadati memorizzato. Questa API non unisce in modo approfondito i metadati.
  • ttl_days int | None: aggiornamento della scadenza facoltativo in giorni. Omettere questo argomento per lasciare invariata la scadenza corrente a meno che non venga specificato ttl_anchor. Passare None per utilizzare MemoryRetentionConfig.max_ttl_days quando la configurazione di conservazione ne imposta una o per cancellare la scadenza quando non è impostata. I valori superiori a MemoryRetentionConfig.max_ttl_days vengono bloccati al massimo con un'avvertenza. I messaggi scaduti non sono disponibili per questa API thread e non possono essere aggiornati.
  • ttl_anchor TimeToLiveAnchor: ancoraggio Time To Live opzionale per un aggiornamento della scadenza. Utilizzare TimeToLiveAnchor.CREATED_AT per l'ora di creazione del messaggio o TimeToLiveAnchor.TIMESTAMP per l'indicatore orario dell'evento memorizzato. Se si specifica ttl_anchor senza ttl_days, viene utilizzata la durata Time To Live predefinita dello schema. Gli aggiornamenti con indicatore orario richiedono un indicatore orario esistente del messaggio ISO-8601 memorizzato. Gli indicatori orari ISO-8601 senza un fuso orario vengono trattati come UTC.
  • **kwargs (Qualsiasi) – gli argomenti con parole chiave impreviste vengono rifiutati.
• Restituzioni: identificativo del record messaggio aggiornato.
• Tipo restituito: str

Note

I campi omessi vengono conservati dal record memorizzato. Il ruolo memorizzato e l'indicatore orario rimangono invariati. La modifica del contenuto aggiorna la cronologia dei messaggi raw e, quando l'estrazione automatica è abilitata, può far sì che l'SDK estragga nuovamente le memorie dal messaggio modificato e dalla cronologia precedente. In modalità INLINE, l'estrazione viene completata prima che venga restituito il metodo. In modalità BACKGROUND, questo metodo viene restituito dopo la riuscita dell'aggiornamento del messaggio raw e l'estrazione in background viene tentata. Questo lavoro di follow-up non influisce sulla normale frequenza di estrazione utilizzata dalle successive chiamate add_messages(). Le memorie estratte esistenti rimangono in vigore mentre le memorie appena estratte dal contenuto modificato possono essere aggiunte. Poiché l'aggiornamento del messaggio raw e qualsiasi scrittura di memoria estratta successiva non si verificano in modo atomico, le memorie estratte possono comunque riflettere il contenuto del messaggio precedente se il lavoro in background non si inserisce nella coda, se un'attesa di capacità di coda configurata raggiunge il timeout o se il lavoro di estrazione successivo non riesce. Inoltre, si noti che le memorie estratte esistenti mantengono la loro scadenza originale quando il TTL di un messaggio di origine cambia.

Esempi

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
run_async_in_sync(
    partial(thread.update_message_async, message_id, content="Edited message")
) == message_id
True

metodo wait_for_memory_extraction

Attendere l'estrazione della memoria in background precedente per questo thread.

Questo metodo attende l'estrazione in background avviata dalle precedenti chiamate add_messages(), add_messages_async(), update_message() o update_message_async() su questo thread tramite lo stesso componente di memoria dell'agente. Se una di queste chiamate sta già finendo, questo metodo include l'estrazione che inizia prima dell'attesa.

Il metodo non attende l'avvio dell'estrazione dopo l'inizio di questa attesa, l'estrazione avviata da un componente di memoria agente diverso o l'esecuzione dell'estrazione in un altro processo. Conteggio degli errori di estrazione completati per questa attesa.

• Parametri: timeout float | None: numero massimo facoltativo di secondi di attesa. L'impostazione predefinita è 300. Passare None per attendere il completamento dell'estrazione in sospeso per questo thread.
• Aumenti: TimeoutError: viene generato quando il timeout scade prima del termine dell'estrazione in background precedente.
• Tipo restituito: nessuna

Esempi

thread.wait_for_memory_extraction(timeout=10)

metodo wait_for_memory_extraction_async (asincrono)

Attendere in modo asincrono l'estrazione della memoria in background precedente.

Questo metodo segue lo stesso funzionamento di wait_for_memory_extraction().

• Parametri: timeout float | None: numero massimo facoltativo di secondi di attesa. L'impostazione predefinita è 300. Passare None per attendere indefinitamente.
• Aumenti: TimeoutError: viene generato quando il timeout scade prima del termine dell'estrazione in background precedente.
• Tipo restituito: nessuna

Esempi

await thread.wait_for_memory_extraction_async(timeout=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. L'eliminazione del thread a livello di client attende l'estrazione in background accettata in precedenza già nota per quel thread, ma non è una barriera di concorrenza globale per altre operazioni sullo stesso thread durante l'eliminazione.

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 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 sintetico del sintetico.

• 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'