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

Creare una nuova istanza di OracleThread.

Esempi

from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c4",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

metodo add_image

Rendi persistente un'immagine associata a questo thread.

description viene memorizzato come testo ricercabile dell'immagine. Quando viene omesso o None, un LLM collegato genera una didascalia. I valori di ambito omessi ereditano gli identificativi utente, agente e thread corrispondenti di questo thread.

metodo add_image_async (asincrono)

Rendi persistente un'immagine associata a questo thread in modo asincrono.

description viene memorizzato come testo ricercabile dell'immagine. Quando viene omesso o None, un LLM collegato genera una didascalia. I valori di ambito omessi ereditano gli identificativi utente, agente e thread corrispondenti di questo thread.

metodo add_memory

Aggiungere una voce di memoria manuale e indicizzarla.

Esempi

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

metodo add_memory_async (asincrono)

Aggiungere una voce di memoria manuale e indicizzarla in modo asincrono.

Esempi

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

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.

I messaggi raw vengono memorizzati prima dell'estrazione automatica in entrambe le modalità. Se l'estrazione successiva o lo storage derivato-memoria non riesce, i messaggi raw rimangono memorizzati mentre le memorie derivate o gli aggiornamenti di riepilogo potrebbero non essere disponibili.

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.

I messaggi raw vengono memorizzati prima dell'estrazione automatica in entrambe le modalità. Se l'estrazione successiva o lo storage derivato-memoria non riesce, i messaggi raw rimangono memorizzati mentre le memorie derivate o gli aggiornamenti di riepilogo potrebbero non essere disponibili.

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.

metodo delete_image

Elimina un'immagine di proprietà di questo thread.

metodo delete_image_async (asincrono)

Elimina un'immagine di proprietà di questo thread in modo asincrono.

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.

Note

Prima di eliminare il record, questo metodo attende l'estrazione in background precedente accettata per questo thread tramite il componente di memoria dell'agente collegato. Non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo.

Esempi

thread.delete_memory("456")
0

metodo delete_memory_async (asincrono)

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

Note

Questo metodo segue il comportamento di attesa e concorrenza dell'estrazione in background documentato da delete_memory().

Esempi

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

metodo delete_message

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

Note

Prima di eliminare il messaggio, questo metodo attende l'estrazione in background precedente accettata per questo thread tramite il componente di memoria dell'agente collegato. Non attende l'accettazione del lavoro dopo l'inizio dell'attesa o l'avvio del lavoro da parte di un altro componente o processo.

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 delete_message_async (asincrono)

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

Note

Questo metodo segue il comportamento di attesa e concorrenza dell'estrazione in background documentato da delete_message().

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

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

Eliminare una relazione di proprietà del thread in base all'ID o alla tupla completa dell'endpoint.

I selettori endpoint-tuple devono utilizzare l'orientamento source-to-target memorizzato.

Esempi

thread.delete_record_link(relation_id="relation-id")
1

Elimina in modo asincrono una relazione di proprietà di questo thread.

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.

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.

Esempi

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

metodo get_message

Restituisci un messaggio di proprietà di questa discussione.

Le parti dell'immagine vengono restituite con i relativi identificatori e descrizioni per impostazione predefinita. Passare included_image_ids per caricare i byte per le parti immagine selezionate. Gli identificativi non correlati vengono ignorati.

metodo get_message_async (asincrono)

Restituisce un messaggio di proprietà dei thread in modo asincrono.

included_image_ids seleziona facoltativamente le parti immagine allegate i cui byte devono essere caricati; omesso o None restituisce solo i metadati dell'immagine.

metodo get_messages

Restituire salvati i messaggi per questa discussione.

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)

Ottenere i messaggi non elaborati dal thread come aggiunto con add_messages in modo asincrono.

Esempi

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

metodo get_summary

Restituisce un sintetico del thread.

Una richiesta full-thread riutilizza o aggiorna il riepilogo permanente. Una richiesta con except_last riepiloga tale prefisso senza modificare il riepilogo permanente dell'intero thread.

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

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

Una richiesta full-thread riutilizza o aggiorna il riepilogo permanente. Una richiesta con except_last riepiloga tale prefisso senza modificare il riepilogo permanente dell'intero thread.

Creare una relazione diretta tra due record di proprietà di questo thread.

Attualmente, entrambi gli endpoint devono essere record simili alla memoria: "memory", "fact", "guideline" o "preference". I tipi di relazione incorporati sono "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" utilizzano la stessa etichetta al contrario.

Entrambi gli endpoint devono appartenere a questo thread. È possibile memorizzare un solo orientamento per una coppia di endpoint. opposite_relation_type assegna un nome alla relazione quando si passa dalla destinazione all'origine; ad esempio, new "supersedes" old diventa old "is_superseded_by" new in tale direzione.

Esempi

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Crea in modo asincrono una relazione tra i record di proprietà di questo thread.

Attualmente, entrambi gli endpoint devono essere record simili alla memoria: "memory", "fact", "guideline" o "preference". I tipi di relazione incorporati sono "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" utilizzano la stessa etichetta al contrario.

metodo list_images

Elenca i record immagine di proprietà di questo thread.

I record restituiti contengono metadati immagine per impostazione predefinita. I byte raw vengono caricati solo se vengono forniti include_bytes=True e image_id.

metodo list_images_async (asincrono)

Elenca i record immagine di proprietà di questo thread in modo asincrono.

I record restituiti contengono metadati immagine per impostazione predefinita. I byte raw vengono caricati solo se vengono forniti include_bytes=True e image_id. L'ambito di questo thread viene applicato automaticamente.

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

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.

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_image

Aggiorna un'immagine di proprietà di questo thread.

Omettere image per conservare i byte esistenti. Se viene fornito image, è necessario fornire mime_type. Omettere description per conservare la descrizione esistente. Passare None per generare una nuova descrizione con l'LLM configurato; una descrizione non nulla la sostituisce direttamente. La scadenza di un'immagine allegata a un messaggio deve essere modificata tramite update_message().

metodo update_image_async (asincrono)

Aggiornare un'immagine di proprietà di questo thread in modo asincrono.

Omettere image per conservare i byte esistenti. Se viene fornito image, è necessario fornire mime_type. Omettere description per conservare la descrizione esistente. Passare None per generare una nuova descrizione con l'LLM configurato; una descrizione non nulla la sostituisce direttamente. I metadati, l'indicatore orario e le impostazioni di scadenza vengono aggiornati quando vengono forniti. La scadenza di un'immagine allegata a un messaggio deve essere modificata tramite update_message_async().

metodo update_memory

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

metodo update_memory_async (asincrono)

Aggiorna un record simile alla memoria di proprietà di questo thread esatto in modo asincrono.

Esempi

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(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.

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.

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

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

Aggiornare una relazione i cui endpoint sono di proprietà di questo thread.

I valori omessi vengono conservati. Quando relation_type passa a un tipo di relazione di memoria incorporata, l'etichetta inversa fissa sostituisce opposite_relation_type.

Esempi

thread.update_record_link("relation-id", relation_type="supports")
1

Aggiorna in modo asincrono una relazione i cui endpoint appartengono a questo thread.

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.

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

Esempi

import asyncio
asyncio.run(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 di messaggi e memoria tramite un handle di thread attende l'estrazione in background precedente già accettata dal client collegato per tale thread. Questa non è una barriera di concorrenza globale per altre istanze, processi o lavori client accettati dopo l'inizio dell'attesa.

Messaggi e contenuti dei messaggi

classe oracleagentmemory.apis.message.Message

Basi: object

Messaggio in-memory condiviso da thread e adattatori LLM.

classe oracleagentmemory.apis.message.MessageContent

Basi: ABC

Classe di base per il contenuto del messaggio strutturato.

classe oracleagentmemory.apis.message.TextContent

Basi: MessageContent

Parte di testo in un messaggio multimodale.

classe oracleagentmemory.apis.message.ImageContent

Basi: MessageContent

Una parte immagine in un messaggio multimodale.

classe oracleagentmemory.apis.message.ImageMimeType

Basi: str, Enum

Tipi MIME supportati per il contenuto immagine.

PNG e WebP animati non sono supportati.

JPEG = 'immagine/JPEG'

PNG = 'immagine/PNG'

WEBP = "immagine/WEBP"

Schede contesto

classe oracleagentmemory.apis.contextcard.ContextCard

Basi: ABC

Oggetto context-card astratto restituito dalle API thread.

proprietà content (abstract)

classe oracleagentmemory.core.contextcard.OracleContextCard

Basi: ContextCard

Scheda contesto restituita da un thread Oracle.

proprietà content

Esempi

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

proprietà formatted_content

Esempi

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

Sintetici

classe oracleagentmemory.apis.summary.Summary

Basi: ABC

Oggetto thread-summary astratto restituito dalle API thread.

proprietà content (abstract)

classe oracleagentmemory.core.summary.OracleSummary

Basi: Summary

Riepilogo restituito da un thread Oracle.

Esempi

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

proprietà content

Esempi

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

proprietà formatted_content

Esempi

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