Unités d'exécution

Cette page présente la poignée concrète des unités d'exécution Oracle ainsi que le type d'aide aux messages destinés aux développeurs.

Fil d'exécution d'Oracle

classe oracleagentmemory.core.OracleThread

Bases : IThread

Fil soutenu par un magasin Oracle.

Cette implémentation intègre et stocke 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.

Notes

• Les messages sont stockés en tant qu'enregistrements individuels (un enregistrement par message).
• La recherche peut être limitée à l'unité d'exécution courante ou être autorisée à renvoyer les résultats de n'importe quelle unité d'exécution (contrôlée par le client).

Créez un descripteur de fil.

• Paramètres :
  • store OracleMemoryStore – Serveur dorsal de magasin partagé utilisé pour conserver les enregistrements intégrés.
  • thread_id str – Identificateur de fil. S'il n'est pas indiqué, un UUID est généré.
  • user_id str – Identificateur d'utilisateur associé à l'unité d'exécution. Si elle est omise, un UUID est généré.
  • agent_id str – Identificateur d'agent associé à l'unité d'exécution. Si elle est omise, un UUID est généré.
  • métadonnées dict[str, Any] | None – Métadonnées facultatives de type JSON associées à l'unité d'exécution.
  • persist_messages_in_config bool – Indique si _to_config doit inclure des instantanés de message brut récents. Réglez automatiquement à False pour les unités d'exécution utilisant le magasin de base de données afin d'éviter d'exporter le contenu de la table de messages au moyen de la configuration d'unité d'exécution.
  • LLM ILlm | None – Adaptateur LLM facultatif utilisé pour l'extraction de mémoire et les mises à jour de sommaire de contexte. Lorsqu'elle est fournie, add_messages extrait les mémoires pertinentes de chaque message ajouté et les stocke en tant qu'enregistrements de mémoire typés ("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. Réglez à -1 pour extraire une seule fois par appel add_messages à l'aide du lot complet des messages nouvellement ajoutés. Par défaut : -1.
  • context_summary_update_frequency int – Nombre de messages après lesquels le sommaire du contexte d'extraction doit être mis à jour. Réglez à -1 pour résumer une seule fois par appel add_messages à l'aide du lot complet des messages nouvellement ajoutés. Par défaut : -1.
  • memory_extraction_frequency int – Nombre de messages après lesquels l'extraction de mémoire est déclenchée. Réglez à -1 pour extraire une seule fois par appel add_messages à l'aide du lot complet des messages nouvellement ajoutés.
  • memory_extraction_token_limit int – Taille maximale, en jetons, des invites de LLM utilisées pour l'extraction de mémoire et l'exécution des mises à jour sommaires. Les invites plus longues sont tronquées. Si négatif ou 0, la troncature des invites est désactivée.
  • context_card_token_limit int – Taille maximale, en jetons, des invites de LLM utilisées pour la récapitulation de carte de contexte. La valeur par défaut est 100_000 tokens. Les invites plus longues sont tronquées. Si négatif ou 0, la troncature des invites est désactivée.
  • max_message_token_length int – Taille maximale, en jetons, de la copie à l'invite de chaque message utilisé lors de l'extraction de mémoire soutenue par le grand modèle de langage et des mises à jour du sommaire du contexte. Le contenu du message stocké reste inchangé. Si la valeur est négative ou égale à 0, aucun raccourcissement du délai d'attente 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. En cas de valeur négative ou 0, aucune limite sortante n'est appliquée lors du raccourcissement basé sur le grand modèle de langage.
  • enable_context_summary bool – Indique s'il faut conserver un sommaire compact en cours d'exécution de l'unité d'exécution. Lorsque cette option est activée et qu'une valeur llm est fournie, le sommaire est mis à jour en fonction de context_summary_update_frequency. Le résumé actuel est fourni comme contexte lors de l'extraction des 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 :
  • contenu str – Contenu textuel à stocker en tant que mémoire.
  • user_id str – Remplacement facultatif de l'identificateur d'utilisateur.
  • agent_id str – Remplacement de l'identificateur d'agent facultatif.
  • thread_id str – Remplacement facultatif de l'identificateur d'unité d'exécution.
  • memory_id str – Identificateur stable fourni par l'appelant facultatif pour cette rangée de mémoire.
  • **store_kwargs (Any) – Options d'écriture propres au magasin transmises au magasin dorsal.
• 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 ou des dictionnaires Message avec role et content (et facultatifs id).
  • **store_kwargs (Any) – Options d'écriture propres au magasin transmises au magasin dorsal.
• Retours : Identificateurs 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

méthode add_messages_async (asynchrone)

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

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

méthode delete_memory

Supprimez un enregistrement de type mémoire (par exemple, une mémoire, un fait, une préférence ou une directive) de ce thread exact par identificateur.

• Paramètres : memory_id str – Identificateur de mémoire. Seuls les enregistrements de type mémoire (memory, guideline, fact, preference) dont thread_id stocké correspond exactement à cette unité d'exécution sont supprimés.
• Retours : Nombre d'enregistrements supprimés (0 ou 1). Retourne 0 lorsque l'identificateur n'existe pas ou appartient à une unité d'exécution différente.
• Type de retour : int

Exemples

thread.delete_memory("456")
0

méthode delete_message

Supprimez un enregistrement de message de ce fil exact par identificateur.

• Parameters (Paramètres) : message_id str – Identificateur de message. Seuls les messages dont thread_id stocké correspond exactement à cette unité d'exécution sont supprimés.
• Retours : Nombre d'enregistrements de message supprimés (0 ou 1). Retourne 0 lorsque l'identificateur n'existe pas ou appartient à une unité d'exécution différente.
• Type de retour : int

Notes

La suppression d'un message supprime uniquement la table des messages bruts. 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 l'unité d'exécution ainsi que les messages et mémoires associés.

Exemples

thread.delete_message("123")
0

méthode get_context_card

Retourne un objet de carte de contexte pour l'unité d'exécution.

Préférez get_context_card_async lorsqu'une mise en oeuvre soutenue par un LLM peut effectuer des E/S de réseau distant.

• Paramètres :
  • fallback_message_count int – Nombre de messages récents à utiliser lors de la dérivation du texte sommaire de secours 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 verbatim.
  • **kwargs (Au choix) – Réservé pour les options de carte de contexte futures. Les arguments de mot clé inattendus soulèvent TypeError.
• Retours : Objet de carte de contexte contenant un sommaire de contexte d'unité d'exécution basé sur les messages les plus récents. Utilisez OracleContextCard.content pour accéder au texte XML rendu.
• Type de retour : OracleContextCard

Notes

Cela utilise la portée de recherche par défaut de l'unité d'exécution avec exact_thread_match=False, de sorte que des mémoires pertinentes d'autres unités d'exécution 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

méthode get_context_card_async (asynchrone)

Retourne de manière asynchrone un objet de carte de contexte pour le thread.

• Paramètres :
  • fallback_message_count int – Nombre de messages récents à utiliser lors de la dérivation du texte sommaire de secours 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 verbatim.
  • **kwargs (Au choix) – Réservé pour les options de carte de contexte futures. Les arguments de mot clé inattendus soulèvent TypeError.
• Retours : Objet de carte de contexte pour l'unité d'exécution.
• Type de retour : OracleContextCard

méthode get_messages

Retourne les messages stockés pour ce thread.

• Paramètres :
  • start int | None – Index de début (basé sur 0). Lorsqu'elle est omise avec end, la fenêtre délimitée la plus récente est retournée.
  • end int | None – Index de fin (exclusif). Lorsqu'elle est omise, une fenêtre limitée des messages les plus récents est retourné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

Retourne un résumé du thread.

Préférez get_summary_async lorsqu'une mise en oeuvre soutenue par un LLM peut effectuer des E/S de réseau distant.

• Paramètres :
  • except_last int – Nombre de messages les plus récents à exclure du sommaire.
  • 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 sommaire formaté dépasse le budget estimé par _estimate_tokens(); le texte retourné est alors limité à int(token_budget * 3.5) caractères. Les valeurs non positives désactivent la limite de sortie.
  • **kwargs (Au choix) – Réservé pour les options de sommaire futures. Les arguments de mot clé inattendus soulèvent TypeError.
• Retours : Objet sommaire contenant le texte sommaire de l'unité d'exécution synthétisée.
• Type de retour : Sommaire OracleSummary

Exemples

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

méthode get_summary_async (asynchrone)

Retourne de manière asynchrone un résumé du thread.

• Paramètres :
  • except_last int – Nombre de messages les plus récents à exclure du sommaire.
  • 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 sommaire formaté dépasse le budget estimé par _estimate_tokens(); le texte retourné est alors limité à int(token_budget * 3.5) caractères. Les valeurs non positives désactivent la limite de sortie.
  • **kwargs (Au choix) – Réservé pour les options de sommaire futures. Les arguments de mot clé inattendus soulèvent TypeError.
• Retours : Objet sommaire contenant le texte sommaire de l'unité d'exécution synthétisée.
• Type de retour : Sommaire OracleSummary

Note : delete_message() supprime uniquement la rangée du message brut. Les mémoires dérivées peuvent toujours être recherchées ou apparaître dans des cartes de contexte. Utilisez OracleAgentMemory.delete_thread() pour supprimer l'unité d'exécution ainsi que les messages et 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

Cartes de contexte

classe oracleagentmemory.apis.contextcard.ContextCard

Bases : ABC

Objet de carte de contexte abstrait retourné par les API d'unité d'exécution.

bien content (abstrait)

• Type de retour : str
• Description : Retourne le texte de la carte de contexte rendu.

classe oracleagentmemory.core.contextcard.OracleContextCard

Bases : ContextCard

Carte de contexte retournée par une unité d'exécution Oracle.

• Paramètres :
  • sommaire str – Texte sommaire intégré dans la carte.
  • sujets Sequence[str] | None – Rubriques d'extraction facultatives associées à l'unité d'exécution.
  • relevant_results Sequence[SearchResult] | None – Enregistrements durables extraits facultatifs inclus dans la carte.
  • recent_messages Sequence[Message] | None – Messages bruts récents facultatifs rendus dans la carte.
  • message_format str – Modèle interne utilisé lors du rendu de recent_messages.

biens content

• Type de retour : str

• Description : Retourne le texte de la carte de contexte rendu.

• Retours : Texte de carte de contexte rendu de type XML adapté à l'assemblage d'invites.
• Type de retour : str

Exemples

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

biens formatted_content

• Type de retour : str

• Description : Retourne le texte de carte de contexte rendu utilisé dans les flux de création d'invites.

• Retours : 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

Sommaires

classe oracleagentmemory.apis.summary.Summary

Bases : ABC

Objet de sommaire d'unité d'exécution abstrait retourné par les API d'unité d'exécution.

bien content (abstrait)

• Type de retour : str
• Description : Retourne le texte sommaire synthétisé.

classe oracleagentmemory.core.summary.OracleSummary

Bases : Summary

Sommaire retourné par une unité d'exécution Oracle.

• Paramètres : contenu str – Texte sommaire synthétisé à partir de la transcription de l'unité d'exécution.

Exemples

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

biens content

• Type de retour : str

• Description : Retourne le texte sommaire synthétisé.

• Retours : Texte sommaire de l'unité d'exécution.
• Type de retour : str

Exemples

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

biens formatted_content

• Type de retour : str

• Description : Retourne le texte sommaire rendu utilisé dans les flux de création d'invites.

• Retours : Texte sommaire affiché.
• Type de retour : str

Exemples

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