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é.
  • 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 que record_type="memory".
  • 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 de contexte 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 même cadence est réutilisée pour l'actualisation des métadonnées de résumé des threads lors des écritures de transcription.
  • 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 utilisées dans l'extraction de mémoire. Les invites plus longues seront tronquées. Si la valeur est négative ou égale à 0, aucune troncation n'est effectué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 mémoire de ce thread exact par identifiant.

• Paramètres : memory_id str – Identificateur de mémoire. Seules les mémoires dont le fichier thread_id stocké correspond exactement à ce thread sont supprimées.
• 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 supprimés (0 ou 1). Renvoie 0 lorsque l'identificateur n'existe pas ou appartient à un autre thread.
• Type de retour : int

Remarques

Une suppression réussie efface l'état thread-summary dérivé afin que les appels de résumé et de carte de contexte ultérieurs soient reconstruits à partir de la transcription restante. Les mémoires dérivées ne sont pas supprimées automatiquement car les mémoires extraites ne persistent pas actuellement par provenance de message.

Exemples 

thread.delete_message("123")
0

méthode get_context_card

Renvoyer une carte de contexte de type XML 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.
• Retours : carte contenant un récapitulatif du contexte de thread basé sur les messages les plus récents.
• Type de retour : str

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

method get_context_card_async (async)

Renvoie de manière asynchrone une carte de contexte de type XML 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.
• Retours : carte contenant un récapitulatif du contexte de thread basé sur les messages les plus récents.
• Type de retour : str

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 : un message d'assistant contenant le récapitulatif, ou une liste vide si le thread ne contient aucun message.
• Type de retour : list[Message]

Exemples 

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
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 : un message d'assistant contenant le récapitulatif, ou une liste vide si le thread ne contient aucun message.
• Type de retour : list[Message]

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