Threads

Cette page présente le gestionnaire de threads Oracle concret ainsi que le type d'aide aux messages destiné aux développeurs.

Thread Oracle

classe oracleagentmemory.core.OracleThread

Bases : IThread

Thread soutenu par un magasin Oracle.

Cette implémentation intègre et stocke à la fois les messages de thread et les mémoires ajoutées manuellement, puis prend en charge la recherche de similarité sur tous les enregistrements stockés.

Remarques

• Les messages sont stockés en tant qu'enregistrements individuels (un enregistrement par message).
• La recherche peut être limitée au thread en cours ou autorisée à renvoyer des résultats à partir de n'importe quel thread (contrôlé par le client).

Créez un nouveau descripteur de thread.

• Paramètres:
  • store OracleMemoryStore : back-end de banque partagée utilisé pour rendre persistants les enregistrements imbriqués.
  • thread_id str : identificateur de thread. S'il n'est pas fourni, un UUID est généré.
  • user_id str : identificateur utilisateur associé au thread. En cas d'omission, un UUID est généré.
  • agent_id str : identificateur d'agent associé au thread. En cas d'omission, un UUID est généré.
  • metadata dict[str, Any] | None : métadonnées de type JSON facultatives associées au thread.
  • persist_messages_in_config bool : indique si _to_config doit inclure des instantanés de messages bruts récents. Définissez automatiquement la valeur sur False pour les threads utilisant la banque de base de données afin d'éviter d'exporter le contenu de la table de messages via la configuration des threads.
  • LLM ILlm | None : adaptateur LLM facultatif utilisé pour l'extraction de mémoire et les mises à jour de récapitulatif de contexte. Lorsqu'il est fourni, add_messages extrait les mémoires pertinentes de chaque message ajouté et les stocke en tant qu'enregistrements de mémoire saisis ("memory", "guideline", "fact" ou "preference").
  • memory_extraction_window int – Nombre de messages les plus récents (y compris le message nouvellement ajouté) à fournir en tant que contexte au LLM lors de l'extraction. Définissez la valeur sur -1 pour extraire une seule fois par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés. La valeur par défaut est -1.
  • context_summary_update_frequency int – Nombre de messages après lesquels le récapitulatif du contexte d'extraction doit être mis à jour. Définissez la valeur sur -1 pour ne résumer qu'une seule fois par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés. La valeur par défaut est -1.
  • memory_extraction_frequency int : nombre de messages après lesquels l'extraction de mémoire est déclenchée. Définissez la valeur sur -1 pour extraire une seule fois par appel add_messages à l'aide du lot complet de messages nouvellement ajoutés.
  • memory_extraction_token_limit int : taille maximale, en jetons, des invites LLM utilisées pour l'extraction de mémoire et l'exécution des mises à jour récapitulatives. Les invites plus longues sont tronquées. Si la valeur est négative ou égale à 0, la troncature d'invite est désactivée.
  • context_card_token_limit int – Taille maximale, en jetons, des invites LLM utilisées pour la synthèse des cartes de contexte. La valeur par défaut est 100_000 tokens. Les invites plus longues sont tronquées. Si la valeur est négative ou égale à 0, la troncature d'invite est désactivée.
  • max_message_token_length int – Taille maximale, en jetons, de la copie d'invite de chaque message utilisé lors de l'extraction de mémoire et des mises à jour de résumé contextuel soutenues par le LLM. Le contenu du message stocké reste inchangé. Si la valeur est négative ou égale à 0, aucun raccourci d'invite n'est effectué. Si un LLM est fourni, les copies d'invite surdimensionnées sont résumées au lieu d'être tronquées.
  • message_shortening_input_token_limit int – Taille maximale, en jetons, de l'extrait de message envoyé au LLM lors du raccourcissement des copies d'invite surdimensionnées. La valeur par défaut est 30_000 tokens. Si la valeur est négative ou égale à 0, aucune limite sortante n'est appliquée pendant le raccourcissement basé sur le LLM.
  • enable_context_summary bool : indique s'il faut conserver un récapitulatif d'exécution compact du thread. Lorsque cette option est activée et qu'une valeur llm est fournie, le récapitulatif est mis à jour en fonction de context_summary_update_frequency. Le résumé courant est fourni comme contexte lors de l'extraction de mémoires.
  • client Any | None

Exemples 

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

méthode add_memory

Ajoutez une entrée de mémoire manuelle et indexez-la.

• Paramètres:
  • content str : contenu texte à stocker en tant que mémoire.
  • user_id str : remplacement facultatif de l'identificateur utilisateur.
  • agent_id str : remplacement facultatif de l'identificateur d'agent.
  • thread_id str : remplacement facultatif de l'identificateur de thread.
  • memory_id str : identificateur stable fourni par l'appelant facultatif pour cette ligne de mémoire.
  • **store_kwargs (N'importe lequel) – Options d'écriture propres à l'emplacement de stockage transférées vers l'emplacement de stockage secondaire.
• Retours : Identificateur de l'enregistrement de mémoire inséré.
• Type de retour : str

Exemples 

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

méthode add_messages

Ajoutez des messages au thread et indexez-les.

• Paramètres:
  • messages list[Message | MessageT] – Liste des messages à ajouter. Les messages peuvent être des objets Message ou des dictionnaires avec role et content (et facultatifs id).
  • **store_kwargs (N'importe lequel) – Options d'écriture propres au magasin transférées vers le magasin de sauvegarde.
• Retours : Identifiants des enregistrements de message insérés.
• Type de retour : list[str]

Exemples 

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

method add_messages_async (async)

Ajoutez des messages de manière asynchrone au thread et indexez-les.

• Paramètres:
  • messages list[Message | MessageT]
  • store_kwargs Any
• Type de retour : list[str]

méthode delete_memory

Supprimer un enregistrement de type mémoire (par exemple, une mémoire, un fait, une préférence ou une consigne) de ce thread exact par identifiant.

• Paramètres : memory_id str – Identificateur de mémoire. Seuls les enregistrements de type mémoire (memory, guideline, fact, preference) dont le fichier thread_id stocké correspond exactement à ce thread sont supprimés.
• Retours : Nombre d'enregistrements supprimés (0 ou 1). Renvoie 0 lorsque l'identificateur n'existe pas ou appartient à un autre thread.
• Type de retour : int

Exemples 

thread.delete_memory("456")
0

méthode delete_message

Supprimer un enregistrement de message de ce thread exact par identifiant.

• Paramètres : message_id str – Identifiant du message. Seuls les messages dont le fichier thread_id stocké correspond exactement à ce thread sont supprimés.
• Retours : Nombre d'enregistrements de message supprimés (0 ou 1). Renvoie 0 lorsque l'identificateur n'existe pas ou appartient à un autre thread.
• Type de retour : int

Remarques

La suppression d'un message supprime uniquement l'enregistrement de message brut. Les mémoires dérivées ne sont pas supprimées car les mémoires extraites ne persistent pas par provenance de message, elles peuvent donc rester consultables ou affecter la sortie de la carte de contexte. Utilisez OracleAgentMemory.delete_thread() pour supprimer le thread ainsi que les messages et les mémoires associés.

Exemples 

thread.delete_message("123")
0

méthode get_context_card

Renvoie un objet context-card pour le thread.

Préférez get_context_card_async lorsqu'une implémentation soutenue par un LLM peut effectuer des E/S réseau distantes.

• Paramètres:
  • fallback_message_count int – Nombre de messages récents à utiliser lors de la dérivation du texte récapitulatif de restauration pour l'extraction et le rendu.
  • max_relevant_results int – Nombre maximal d'enregistrements durables extraits à inclure.
  • max_recent_messages int – Nombre maximal de messages bruts de fin à intégrer mot pour mot.
  • **kwargs (N'importe lequel) – Réservé aux futures options de carte contextuelle. Les arguments de mot-clé inattendus déclenchent TypeError.
• Renvoie : objet de carte de contexte contenant un récapitulatif de contexte de thread basé sur les messages les plus récents. Utilisez OracleContextCard.content pour accéder au texte de type XML affiché.
• Type de retour : OracleContextCard

Remarques

Cela utilise la portée de recherche par défaut du thread avec exact_thread_match=False, de sorte que les mémoires pertinentes d'autres threads pour le même utilisateur/agent peuvent être incluses.

Exemples 

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

method get_context_card_async (async)

Renvoie de manière asynchrone un objet context-card pour le thread.

• Paramètres:
  • fallback_message_count int – Nombre de messages récents à utiliser lors de la dérivation du texte récapitulatif de restauration pour l'extraction et le rendu.
  • max_relevant_results int – Nombre maximal d'enregistrements durables extraits à inclure.
  • max_recent_messages int – Nombre maximal de messages bruts de fin à intégrer mot pour mot.
  • **kwargs (N'importe lequel) – Réservé aux futures options de carte contextuelle. Les arguments de mot-clé inattendus déclenchent TypeError.
• Renvoie : objet de carte de contexte pour le thread.
• Type de retour : OracleContextCard

méthode get_messages

Renvoyer les messages stockés pour ce sujet de discussion.

• Paramètres:
  • start int | None : index de démarrage (basé sur 0). Lorsqu'elle est omise avec end, la fenêtre limitée la plus récente est renvoyée.
  • end int | None : index de fin (exclusif). Lorsqu'elle est omise, une fenêtre délimitée des messages les plus récents est renvoyée. Transmettez None ou -1 pour demander explicitement tous les messages à partir de start.
• Retours : messages dans l'ordre chronologique.
• Type de retour : list[Message]

Exemples 

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

méthode get_summary

Renvoyer un résumé au mieux du thread.

Préférez get_summary_async lorsqu'une implémentation soutenue par un LLM peut effectuer des E/S réseau distantes.

• Paramètres:
  • sauf_last int – Nombre de messages les plus récents à exclure du récapitulatif.
  • token_budget int – Budget de jeton logiciel. Lorsqu'elle est omise, une valeur par défaut limitée est appliquée. Les valeurs positives ne sont tronquées que lorsque le récapitulatif formaté dépasse le budget estimé par _estimate_tokens(). Le texte renvoyé est alors limité à int(token_budget * 3.5) caractères. Les valeurs non positives désactivent la limite de sortie.
  • **kwargs (N'importe lequel) – Réservé aux options de récapitulatif futures. Les arguments de mot-clé inattendus déclenchent TypeError.
• Renvoie : objet récapitulatif contenant le texte récapitulatif du thread synthétisé.
• Type de retour : OracleSummary

Exemples 

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

method get_summary_async (async)

Renvoie de manière asynchrone un récapitulatif au mieux du thread.

• Paramètres:
  • sauf_last int – Nombre de messages les plus récents à exclure du récapitulatif.
  • token_budget int – Budget de jeton logiciel. Lorsqu'elle est omise, une valeur par défaut limitée est appliquée. Les valeurs positives ne sont tronquées que lorsque le récapitulatif formaté dépasse le budget estimé par _estimate_tokens(). Le texte renvoyé est alors limité à int(token_budget * 3.5) caractères. Les valeurs non positives désactivent la limite de sortie.
  • **kwargs (N'importe lequel) – Réservé aux options de récapitulatif futures. Les arguments de mot-clé inattendus déclenchent TypeError.
• Renvoie : objet récapitulatif contenant le texte récapitulatif du thread synthétisé.
• Type de retour : OracleSummary

Remarque : delete_message() supprime uniquement la ligne de message brut. Les mémoires dérivées peuvent toujours être consultables ou apparaître dans des cartes de contexte. Utilisez OracleAgentMemory.delete_thread() pour supprimer le thread ainsi que les messages et les mémoires associés.

Messages

classe oracleagentmemory.apis.thread.Message

Bases : object

• Paramètres:
  • rôle str
  • contenu str
  • horodatage str | None
  • métadonnées dict[str, Any] | None
  • id str | None

Fiches contextuelles

classe oracleagentmemory.apis.contextcard.ContextCard

Bases : ABC

Objet de carte de contexte abstrait renvoyé par les API de thread.

property content (résumé)

• Type de retour : str
• Description : renvoie le texte de la carte contextuelle affichée.

classe oracleagentmemory.core.contextcard.OracleContextCard

Bases : ContextCard

Carte de contexte renvoyée par un thread Oracle.

• Paramètres:
  • summary str – Texte récapitulatif intégré à la carte.
  • sujets Sequence[str] | None : rubriques d'extraction facultatives associées au thread.
  • relevant_results Sequence[SearchResult] | None : enregistrements durables extraits facultatifs inclus dans la carte.
  • recent_messages Sequence[Message] | None : messages bruts récents facultatifs affichés dans la carte.
  • message_format str – Modèle interne utilisé lors du rendu de recent_messages.

propriété content

• Type de retour : str

• Description : renvoie le texte de la carte contextuelle affichée.

• Renvoie : texte de carte de contexte rendu de type XML adapté à l'assemblage d'invite.
• Type de retour : str

Exemples 

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

propriété formatted_content

• Type de retour : str

• Description : renvoie le texte de carte de contexte affiché utilisé dans les flux de création d'invite.

• Renvoie : texte de carte de contexte rendu de type XML.
• Type de retour : str

Exemples 

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

Récapitulatifs

classe oracleagentmemory.apis.summary.Summary

Bases : ABC

Objet récapitulatif de thread abstrait renvoyé par les API de thread.

property content (résumé)

• Type de retour : str
• Description : renvoie le texte récapitulatif synthétisé.

classe oracleagentmemory.core.summary.OracleSummary

Bases : Summary

Récapitulatif renvoyé par un thread Oracle.

• Paramètres : content str – Texte récapitulatif synthétisé à partir de la transcription du thread.

Exemples 

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

propriété content

• Type de retour : str

• Description : renvoie le texte récapitulatif synthétisé.

• Retours : Texte de synthèse pour le thread.
• Type de retour : str

Exemples 

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

propriété formatted_content

• Type de retour : str

• Description : renvoie le texte récapitulatif affiché utilisé dans les flux de création d'invite.

• Retours : Texte récapitulatif affiché.
• Type de retour : str

Exemples 

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