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

• Nachrichten werden als einzelne Datensätze gespeichert (ein Datensatz pro Nachricht).
• Die Suche kann auf den aktuellen Thread beschränkt sein oder Ergebnisse aus einem beliebigen Thread zurückgeben (Client-gesteuert).

Neuen Thread-Handle erstellen.

• Parameter:
  • store OracleMemoryStore: Shared Store-Backend, das zum Persistieren eingebetteter Datensätze verwendet wird.
  • thread_id str: Thread-ID. Wenn keine Angabe gemacht wird, wird eine UUID generiert.
  • user_id str: Mit dem Thread verknüpfte Benutzer-ID. Wird kein Wert angegeben, wird eine UUID generiert.
  • agent_id str: Agent-ID, die mit dem Thread verknüpft ist. Wird kein Wert angegeben, wird eine UUID generiert.
  • Metadaten dict[str, Any] | None – Optionale JSON-ähnliche Metadaten, die mit dem Thread verknüpft sind.
  • persist_messages_in_config bool – Gibt an, ob _to_config aktuelle Raw-Nachrichten-Snapshots enthalten soll. Wird automatisch für Threads, die den DB-Speicher verwenden, auf False gesetzt, um zu vermeiden, dass Inhalt der Meldungstabelle über die Threadkonfiguration exportiert wird.
  • LLM ILlm | None – Optionaler LLM-Adapter für Speicherextraktion und Aktualisierungen der Kontextübersicht. Wenn angegeben, extrahiert add_messages relevante Speicher aus jeder hinzugefügten Nachricht und speichert sie als eingegebene Speicherdatensätze ("memory", "guideline", "fact" oder "preference").
  • memory_extraction_window int: Anzahl der neuesten Nachrichten (einschließlich der neu hinzugefügten Nachrichten), die während der Extraktion als Kontext für das LLM bereitgestellt werden. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zu extrahieren. Standard ist -1.
  • context_summary_update_frequency int – Anzahl der Nachrichten, nach denen die Extraktionskontextübersicht aktualisiert werden soll. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zusammenzufassen. Standard ist -1.
  • memory_extraction_frequency int: Anzahl der Nachrichten, nach denen die Speicherextraktion ausgelöst wird. Setzen Sie diesen Wert auf -1, um nur einmal pro add_messages-Aufruf mit dem vollständigen Batch neu hinzugefügter Nachrichten zu extrahieren.
  • memory_extraction_token_limit int – Maximale Größe der LLM-Prompts, die für die Speicherextraktion und die Ausführung von Zusammenfassungsaktualisierungen verwendet werden, in Token. Längere Eingabeaufforderungen werden abgeschnitten. Wenn negativ oder 0, ist das Abschneiden der Eingabeaufforderung deaktiviert.
  • context_card_token_limit int – Maximale Größe in Token der LLM-Eingabeaufforderungen, die für die Kontextkartenzusammenfassung verwendet werden. Standard ist 100_000-Token. Längere Eingabeaufforderungen werden abgeschnitten. Wenn negativ oder 0, ist das Abschneiden der Eingabeaufforderung deaktiviert.
  • max_message_token_length int – Maximale Größe der Prompt-Time-Kopie jeder Nachricht, die während der LLM-gesicherten Speicherextraktion und Aktualisierungen der Kontextzusammenfassung verwendet wird, in Token. Der gespeicherte Nachrichteninhalt bleibt unverändert. Wenn negativ oder 0, wird keine Verkürzung der Prompt-Zeit durchgeführt. Wenn ein LLM bereitgestellt wird, werden übergroße Prompt-Kopien zusammengefasst und nicht abgeschnitten.
  • message_shortening_input_token_limit int – Maximale Größe des Nachrichtenauszugs in Token, der an das LLM gesendet wird, wenn übergroße Prompt-Kopien gekürzt werden. Standard ist 30_000-Token. Wenn negativ oder 0, wird während der LLM-basierten Verkürzung keine ausgehende Grenze angewendet.
  • enable_context_summary bool – Gibt an, ob eine kompakte Zusammenfassung des Threads ausgeführt werden soll. Wenn diese Option aktiviert ist und eine llm angegeben ist, wird die Übersicht gemäß context_summary_update_frequency aktualisiert. Die aktuelle Zusammenfassung wird als Kontext beim Extrahieren von Speichern bereitgestellt.
  • Client Any | None

Beispiele

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

Methode add_memory

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

• Parameter:
  • content str: Textinhalt, der als Speicher gespeichert werden soll.
  • user_id str: Optionales Überschreiben der Benutzer-ID.
  • agent_id str: Optionales Überschreiben der Agent-ID.
  • thread_id str – Optionales Überschreiben der Thread-ID.
  • memory_id str – Optionale vom Aufrufer bereitgestellte stabile ID für diese Speicherzeile.
  • **store_kwargs (Beliebige) – Speicherspezifische Schreiboptionen, die an den zugrunde liegenden Speicher weitergeleitet werden.
• Rückgaben: ID des eingefügten Speicherdatensatzes.
• Rückgabetyp: str

Beispiele

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

Methode add_messages

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

• Parameter:
  • Nachrichten list[Message | MessageT]: Liste der anzuhängenden Nachrichten. Nachrichten können Message-Objekte oder Wörterbücher mit role und content (und optional id) sein.
  • **store_kwargs (Beliebige) – Speicherspezifische Schreiboptionen, die an den zugrunde liegenden Speicher weitergeleitet werden.
• Rücksendungen: IDs eingefügter Meldungsdatensätze.
• Rückgabetyp: list[str]

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.

• Parameter:
  • Nachrichten list[Message | MessageT]
  • store_kwargs Any
• Rückgabetyp: list[str]

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.

• Parameter: memory_id str – Speicher-ID. Es werden nur speicherähnliche Datensätze (memory, guideline, fact, preference) gelöscht, deren gespeicherte thread_id genau mit diesem Thread übereinstimmt.
• Rücksendungen: Anzahl der gelöschten Datensätze (0 oder 1). Gibt 0 zurück, wenn die ID nicht vorhanden ist oder zu einem anderen Thread gehört.
• Rückgabetyp: int

Beispiele

thread.delete_memory("456")
0

Methode delete_message

Meldungsdatensatz aus diesem Thread nach ID löschen.

• Parameter: message_id str: Nachrichten-ID. Nur Nachrichten, deren gespeicherte thread_id genau mit diesem Thread übereinstimmt, werden gelöscht.
• Rücksendungen: Anzahl der gelöschten Nachrichtendatensätze (0 oder 1). Gibt 0 zurück, wenn die ID nicht vorhanden ist oder zu einem anderen Thread gehört.
• Rückgabetyp: int

Hinweise

Beim Löschen einer Nachricht wird nur der Raw-Nachrichtendatensatz entfernt. Abgeleitete Speicher werden nicht gelöscht, da extrahierte Speicher nicht pro Nachrichtenherkunft beibehalten werden, sodass 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.

• Parameter:
  • fallback_message_count int: Anzahl der letzten Nachrichten, die verwendet werden sollen, wenn der Fallback-Zusammenfassungstext zum Abrufen und Rendering abgeleitet wird.
  • max_relevant_results int – Maximale Anzahl der abgerufenen dauerhaften Datensätze, die eingeschlossen werden sollen.
  • max_recent_messages int: Maximale Anzahl der nachgestellten Raw-Nachrichten, die ausführlich eingebettet werden.
  • **kwargs (Beliebig) – Reserviert für zukünftige Kontextkartenoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Ein Kontextkartenobjekt, das eine Threadkontextübersicht basierend auf den neuesten Nachrichten enthält. Verwenden Sie OracleContextCard.content, um auf den gerenderten XML-ähnlichen Text zuzugreifen.
• Rückgabetyp: OracleContextCard

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

Methode get_context_card_async (asynchron)

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

• Parameter:
  • fallback_message_count int: Anzahl der letzten Nachrichten, die verwendet werden sollen, wenn der Fallback-Zusammenfassungstext zum Abrufen und Rendering abgeleitet wird.
  • max_relevant_results int – Maximale Anzahl der abgerufenen dauerhaften Datensätze, die eingeschlossen werden sollen.
  • max_recent_messages int: Maximale Anzahl der nachgestellten Raw-Nachrichten, die ausführlich eingebettet werden.
  • **kwargs (Beliebig) – Reserviert für zukünftige Kontextkartenoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Ein Kontextkartenobjekt für den Thread.
• Rückgabetyp: OracleContextCard

Methode get_messages

Gespeicherte Nachrichten für diesen Thread zurückgeben.

• Parameter:
  • start int | None: Startindex (0-basiert). Wenn zusammen mit end ausgelassen wird, wird das zuletzt beschränkte Fenster zurückgegeben.
  • end int | None: Endindex (exklusiv). Wenn diese Option ausgelassen wird, wird ein begrenztes Fenster mit den neuesten Nachrichten zurückgegeben. Übergeben Sie None oder -1, um alle Nachrichten ab start explizit anzufordern.
• Rückgaben: Nachrichten in chronologischer Reihenfolge.
• Liste Rückgabetyp:[Nachricht]

Beispiele

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

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.

• Parameter:
  • except_last int – Anzahl der letzten Nachrichten, die aus der Übersicht ausgeschlossen werden sollen.
  • token_budget int: Budget für Soft-Token. Wenn kein Wert angegeben wird, wird ein gebundener Standardwert angewendet. Positive Werte werden nur abgeschnitten, wenn die formatierte Übersicht das Budget nach der Schätzung von _estimate_tokens() überschreitet. Der zurückgegebene Text wird dann auf int(token_budget * 3.5) Zeichen begrenzt. Nicht positive Werte deaktivieren die Ausgabegrenze.
  • **kwargs (Beliebig) – Reserviert für zukünftige Übersichtsoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Zusammenfassungsobjekt mit dem Synthesized Thread-Zusammenfassungstext.
• Rückgabetyp: OracleSummary

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.

• Parameter:
  • except_last int – Anzahl der letzten Nachrichten, die aus der Übersicht ausgeschlossen werden sollen.
  • token_budget int: Budget für Soft-Token. Wenn kein Wert angegeben wird, wird ein gebundener Standardwert angewendet. Positive Werte werden nur abgeschnitten, wenn die formatierte Übersicht das Budget nach der Schätzung von _estimate_tokens() überschreitet. Der zurückgegebene Text wird dann auf int(token_budget * 3.5) Zeichen begrenzt. Nicht positive Werte deaktivieren die Ausgabegrenze.
  • **kwargs (Beliebig) – Reserviert für zukünftige Übersichtsoptionen. Unerwartete Schlüsselwortargumente lösen TypeError aus.
• Rückgaben: Zusammenfassungsobjekt mit dem Synthesized Thread-Zusammenfassungstext.
• Rückgabetyp: OracleSummary

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.

Nachrichten

Klasse oracleagentmemory.apis.thread.Message

Basis: object

• Parameter:
  • Rolle str
  • Inhalt str
  • Zeitstempel str | None
  • Metadaten dict[str, Any] | None
  • ID str | None

Kontextkarten

Klasse oracleagentmemory.apis.contextcard.ContextCard

Basen: ABC

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

Eigenschaft content (Übung)

• Rückgabetyp: str
• Beschreibung: Gibt den gerenderten Kontextkartentext zurück.

Klasse oracleagentmemory.core.contextcard.OracleContextCard

Basis: ContextCard

Von einem Oracle-Thread zurückgegebene Kontextkarte.

• Parameter:
  • Zusammenfassung str: Zusammenfassungstext, der in die Karte eingebettet ist.
  • Themen Sequence[str] | None – Optionale Abrufthemen, die mit dem Thread verknüpft sind.
  • relevant_results Sequence[SearchResult] | None – Optionale abgerufene dauerhafte Datensätze in der Karte.
  • recent_messages Sequence[Message] | None: Optionale letzte Raw-Nachrichten, die in der Karte gerendert werden.
  • message_format str: Interne Vorlage, die beim Rendern von recent_messages verwendet wird.

Eigenschaft content

• Rückgabetyp: str

• Beschreibung: Gibt den gerenderten Kontextkartentext zurück.

• Rückgaben: XML-ähnlicher gerenderter Kontextkartentext, der für die Prompt-Assemblierung geeignet ist.
• Rückgabetyp: str

Beispiele

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

Eigenschaft formatted_content

• Rückgabetyp: str

• Beschreibung: Gibt den gerenderten Kontextkartentext zurück, der in Prompt-Building-Abläufen verwendet wird.

• Rückgaben: XML-ähnlicher gerenderter Kontextkartentext.
• Rückgabetyp: str

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)

• Rückgabetyp: str
• Beschreibung: Gibt den synthetischen Zusammenfassungstext zurück.

Klasse oracleagentmemory.core.summary.OracleSummary

Basis: Summary

Von einem Oracle-Thread zurückgegebene Übersicht.

• Parameter: content str – Zusammenfassungstext, der aus dem Threadtranskript synthetisiert wird.

Beispiele

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

Eigenschaft content

• Rückgabetyp: str

• Beschreibung: Gibt den synthetischen Zusammenfassungstext zurück.

• Rückgaben: Zusammenfassungstext für den Thread.
• Rückgabetyp: str

Beispiele

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

Eigenschaft formatted_content

• Rückgabetyp: str

• Beschreibung: Gibt den gerenderten Übersichtstext zurück, der in Flüssen zur Prompt-Erstellung verwendet wird.

• Rückgaben: Gerenderter Übersichtstext.
• Rückgabetyp: str

Beispiele

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