Threads

Auf dieser Seite wird das konkrete Oracle-Thread-Handle zusammen mit dem Entwickler-Helper-Typ vorgestellt.

Oracle-Thread

Klasse oracleagentmemory.core.OracleThread

Basen: IThread

Thread wird von einem Oracle-Speicher unterstützt.

Diese Implementierung integriert und speichert sowohl Thread-Nachrichten als auch manuell hinzugefügte Speicher und unterstützt dann die Ähnlichkeitssuche über alle gespeicherten Datensätze.

Hinweise

Erstellen Sie eine neue OracleThread-Instanz.

Beispiele

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

Methode add_memory

Fügen Sie einen manuellen Speichereintrag hinzu, und indexieren Sie ihn.

Beispiele

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

Methode add_memory_async (asynchron)

Fügen Sie einen Speicher asynchron hinzu.

Methode add_messages

Fügen Sie dem Thread Nachrichten hinzu, und indexieren Sie sie.

Im Hintergrundextraktionsmodus gibt diese Methode zurück, nachdem Raw-Nachrichten eingefügt wurden und die Hintergrundextraktion im Hintergrund versucht wurde.

Hinweise

In MemoryExtractionMode.BACKGROUND werden Raw-Nachrichten persistiert, bevor extrahierte Speicher gespeichert werden. Wenn die Hintergrundextraktion nicht in eine Warteschlange gestellt wird oder wenn eine konfigurierte Warteschlangenkapazität den Timeout erreicht, bleiben die eingefügten Raw-Nachrichten gespeichert, und der Aufruf wird entweder ohne extrahierte Speicher fortgesetzt, oder TimeoutError wird je nach background_extraction_queue_full_behavior ausgelöst.

Beispiele

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

Methode add_messages_async (asynchron)

Fügen Sie dem Thread asynchron Nachrichten hinzu, und indexieren Sie sie.

Im Hintergrundextraktionsmodus gibt diese Methode zurück, nachdem Raw-Nachrichten eingefügt wurden und die Hintergrundextraktion im Hintergrund versucht wurde.

In MemoryExtractionMode.BACKGROUND werden Raw-Nachrichten persistiert, bevor extrahierte Speicher gespeichert werden. Wenn die Hintergrundextraktion nicht in eine Warteschlange gestellt wird oder wenn eine konfigurierte Warteschlangenkapazität den Timeout erreicht, bleiben die eingefügten Raw-Nachrichten gespeichert, und der Aufruf wird entweder ohne extrahierte Speicher fortgesetzt, oder TimeoutError wird je nach background_extraction_queue_full_behavior ausgelöst.

Methode delete_memory

Löschen Sie einen speicherähnlichen Datensatz (z. B. einen Speicher, einen Fakt, eine Voreinstellung oder eine Richtlinie) nach Kennung aus diesem Thread.

Beispiele

thread.delete_memory("456")
0

Methode delete_message

Meldungsdatensatz aus diesem Thread nach ID löschen.

Hinweise

Beim Löschen einer Nachricht wird nur der Raw-Nachrichtendatensatz entfernt. Abgeleitete Speicher werden nicht gelöscht, da wir noch nicht verfolgen, welche extrahierten Speicher aus welcher Nachricht stammen, so dass sie durchsuchbar bleiben oder sich immer noch auf die Kontextkartenausgabe auswirken können. Verwenden Sie OracleAgentMemory.delete_thread(), um den Thread zusammen mit den zugehörigen Nachrichten und Speichern zu löschen.

Beispiele

thread.delete_message("123")
0

Methode get_context_card

Gibt ein Kontextkartenobjekt für den Thread zurück.

Wählen Sie get_context_card_async, wenn eine LLM-gestützte Implementierung Remote-Netzwerk-I/O ausführen kann.

Hinweise

Dabei wird der standardmäßige Suchgeltungsbereich des Threads mit exact_thread_match=False verwendet, sodass relevante Speicher aus anderen Threads für denselben Benutzer/Agent enthalten sein können.

Beispiele

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

Methode get_context_card_async (asynchron)

Gibt ein Kontextkartenobjekt für den Thread asynchron zurück.

Beispiele

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

Methode get_messages

Gespeicherte Nachrichten für diesen Thread zurückgeben.

Beispiele

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

Methode get_messages_async (asynchron)

Raw Thread-Nachrichten asynchron zurückgeben

Methode get_summary

Gibt eine Best Effort-Zusammenfassung des Threads zurück.

Wählen Sie get_summary_async, wenn eine LLM-gestützte Implementierung Remote-Netzwerk-I/O ausführen kann.

Beispiele

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

Methode get_summary_async (asynchron)

Gibt asynchron eine Best Effort-Zusammenfassung des Threads zurück.

Synchron nach Datensätzen suchen, die für eine Abfrage relevant sind.

Hinweise

Ausgelassene Geltungsbereichsfelder übernehmen den Standardsuchgeltungsbereich dieses Threads: exakter Benutzer- und Agent-Abgleich plus aktuellem user_id, agent_id und thread_id dieses Threads. Bei der Standardthreadsuche wird exact_thread_match=False absichtlich beibehalten, sodass relevante Datensätze aus anderen Threads für denselben Benutzer/Agent zurückgegeben werden können. Übergeben Sie exact_thread_match=True, um die Ergebnisse auf den aktuellen Thread zu beschränken. Explizite None-Geltungsbereichswerte folgen weiterhin den aufgelösten exakten Übereinstimmungsregeln: exact_*_match=False lässt diese Dimension uneingeschränkt zu, während exact_*_match=True nur gespeicherten None-Werten entspricht.

Explizite max_results-Werte müssen mindestens 1 sein. Wenn das Argument weggelassen wird, wird der Standardwert 10 verwendet. Dies ist ein oberer Grenzwert: Der Aufruf gibt möglicherweise weniger als max_results-Ergebnisse zurück, wenn Filter zu restriktiv sind, wenn weniger übereinstimmende Datensätze vorhanden sind oder das implementierungsspezifische Suchverhalten vorliegt.

Methode search_async (asynchron)

Suche asynchron nach Datensätzen, die für eine Abfrage relevant sind.

Hinweise

Ausgelassene Geltungsbereichsfelder übernehmen den Standardsuchgeltungsbereich dieses Threads: exakter Benutzer- und Agent-Abgleich plus aktuellem user_id, agent_id und thread_id dieses Threads. Bei der Standardthreadsuche wird exact_thread_match=False absichtlich beibehalten, sodass relevante Datensätze aus anderen Threads für denselben Benutzer/Agent zurückgegeben werden können. Übergeben Sie exact_thread_match=True, um die Ergebnisse auf den aktuellen Thread zu beschränken. Explizite None-Geltungsbereichswerte folgen weiterhin den aufgelösten exakten Übereinstimmungsregeln: exact_*_match=False lässt diese Dimension uneingeschränkt zu, während exact_*_match=True nur gespeicherten None-Werten entspricht.

Explizite max_results-Werte müssen mindestens 1 sein. Wenn das Argument weggelassen wird, wird der Standardwert 10 verwendet. Dies ist ein oberer Grenzwert: Der Aufruf gibt möglicherweise weniger als max_results-Ergebnisse zurück, wenn Filter zu restriktiv sind, wenn weniger übereinstimmende Datensätze vorhanden sind oder das implementierungsspezifische Suchverhalten vorliegt.

Methode update_memory

Aktualisieren Sie einen speicherähnlichen Datensatz, der diesem Thread gehört.

Methode update_memory_async (asynchron)

Aktualisieren Sie einen speicherähnlichen Datensatz asynchron.

Beispiele

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

Methode update_message

Aktualisieren Sie einen Raw-Nachrichtendatensatz, der diesem Thread gehört.

Hinweise

Ausgelassene Felder werden aus dem gespeicherten Datensatz beibehalten. Gespeicherte Rolle und Zeitstempel bleiben unverändert. Wenn Sie Inhalte bearbeiten, wird die Rohnachrichtenhistorie aktualisiert. Wenn die automatische Extraktion aktiviert ist, kann das SDK dazu führen, dass Speicher aus der bearbeiteten Nachricht und der früheren Historie neu extrahiert werden. Im Modus INLINE wird diese Extraktion abgeschlossen, bevor diese Methode zurückgegeben wird. Im Modus BACKGROUND gibt diese Methode zurück, nachdem die Aktualisierung der Raw-Nachricht erfolgreich war und die Hintergrundextraktion versucht wurde. Diese Nachsorgearbeiten wirken sich nicht auf die normale Extraktionshäufigkeit aus, die von späteren add_messages()-Aufrufen verwendet wird. Vorhandene extrahierte Speicher bleiben vorhanden, während neu extrahierte Speicher aus dem bearbeiteten Inhalt hinzugefügt werden können. Da die Aktualisierung der Raw-Nachricht und spätere Schreibvorgänge im extrahierten Speicher nicht atomar erfolgen, können extrahierte Speicher weiterhin den früheren Nachrichteninhalt widerspiegeln, wenn die Hintergrundarbeit nicht in eine Warteschlange gestellt wird, wenn eine konfigurierte Warteschlangenkapazität ihren Timeout erreicht oder die spätere Extraktion fehlschlägt. Beachten Sie außerdem, dass vorhandene extrahierte Speicher ihren ursprünglichen Ablauf beibehalten, wenn sich die TTL einer Quellnachricht ändert.

Beispiele

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

Methode update_message_async (asynchron)

Aktualisieren Sie einen Raw-Nachrichtendatensatz, der diesem Thread gehört, asynchron.

Hinweise

Ausgelassene Felder werden aus dem gespeicherten Datensatz beibehalten. Gespeicherte Rolle und Zeitstempel bleiben unverändert. Wenn Sie Inhalte bearbeiten, wird die Rohnachrichtenhistorie aktualisiert. Wenn die automatische Extraktion aktiviert ist, kann das SDK dazu führen, dass Speicher aus der bearbeiteten Nachricht und der früheren Historie neu extrahiert werden. Im Modus INLINE wird diese Extraktion abgeschlossen, bevor diese Methode zurückgegeben wird. Im Modus BACKGROUND gibt diese Methode zurück, nachdem die Aktualisierung der Raw-Nachricht erfolgreich war und die Hintergrundextraktion versucht wurde. Diese Nachsorgearbeiten wirken sich nicht auf die normale Extraktionshäufigkeit aus, die von späteren add_messages()-Aufrufen verwendet wird. Vorhandene extrahierte Speicher bleiben vorhanden, während neu extrahierte Speicher aus dem bearbeiteten Inhalt hinzugefügt werden können. Da die Aktualisierung der Raw-Nachricht und spätere Schreibvorgänge im extrahierten Speicher nicht atomar erfolgen, können extrahierte Speicher weiterhin den früheren Nachrichteninhalt widerspiegeln, wenn die Hintergrundarbeit nicht in eine Warteschlange gestellt wird, wenn eine konfigurierte Warteschlangenkapazität ihren Timeout erreicht oder die spätere Extraktion fehlschlägt. Beachten Sie außerdem, dass vorhandene extrahierte Speicher ihren ursprünglichen Ablauf beibehalten, wenn sich die TTL einer Quellnachricht ändert.

Beispiele

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

Methode wait_for_memory_extraction

Warten Sie auf eine frühere Hintergrundspeicherextraktion für diesen Thread.

Diese Methode wartet auf Hintergrundextraktion, die von früheren add_messages()-, add_messages_async()-, update_message()- oder update_message_async()-Aufrufen in diesem Thread über dieselbe Agent-Speicherkomponente gestartet wurde. Wenn einer dieser Aufrufe bereits abgeschlossen ist, enthält diese Methode die Extraktion, die vor dem Warten beginnt.

Die Methode wartet nicht auf den Start der Extraktion nach Beginn dieser Wartezeit, auf die Extraktion, die von einer anderen Agent-Speicherkomponente gestartet wurde, oder auf die Extraktion, die in einem anderen Prozess ausgeführt wird. Extraktionsfehler zählen als beendet für diese Wartezeit.

Beispiele

thread.wait_for_memory_extraction(timeout=10)

Methode wait_for_memory_extraction_async (asynchron)

Asynchrones Warten auf frühere Hintergrundspeicherextraktion.

Diese Methode folgt demselben Verhalten wie wait_for_memory_extraction().

Beispiele

await thread.wait_for_memory_extraction_async(timeout=10)

Hinweis: delete_message() löscht nur die Zeile mit Raw-Nachrichten. Abgeleitete Speicher können weiterhin durchsucht werden oder in Kontextkarten angezeigt werden. Verwenden Sie OracleAgentMemory.delete_thread(), um den Thread zusammen mit den zugehörigen Nachrichten und Speichern zu löschen. Der Client-Level-Thread-Löschvorgang wartet auf die zuvor akzeptierte Hintergrundextraktion, die bereits für diesen Thread bekannt ist. Es handelt sich jedoch nicht um eine globale Nebenläufigkeitsbarriere für andere Vorgänge im selben Thread, während der Löschvorgang ausgeführt wird.

Nachrichten

Klasse oracleagentmemory.apis.thread.Message

Basis: object

Kontextkarten

Klasse oracleagentmemory.apis.contextcard.ContextCard

Basen: ABC

Abstraktes Kontextkartenobjekt, das von Thread-APIs zurückgegeben wird.

Eigenschaft content (Übung)

Klasse oracleagentmemory.core.contextcard.OracleContextCard

Basis: ContextCard

Von einem Oracle-Thread zurückgegebene Kontextkarte.

Eigenschaft content

Beispiele

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

Eigenschaft formatted_content

Beispiele

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

Übersichten

Klasse oracleagentmemory.apis.summary.Summary

Basen: ABC

Von Thread-APIs zurückgegebenes abstraktes Thread-Zusammenfassungsobjekt.

Eigenschaft content (Übung)

Klasse oracleagentmemory.core.summary.OracleSummary

Basis: Summary

Von einem Oracle-Thread zurückgegebene Übersicht.

Beispiele

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

Eigenschaft content

Beispiele

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

Eigenschaft formatted_content

Beispiele

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