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é.
  • 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 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. 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 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. La même fréquence est réutilisée pour actualiser les métadonnées de récapitulation des unités d'exécution lors des écritures de transcription.
  • 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 utilisées pour l'extraction de mémoire. Les invites plus longues seront tronquées. Si négatif ou 0, aucune troncature n'est effectué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 mémoire de ce thread exact par identificateur.

• Paramètres : memory_id str – Identificateur de mémoire. Seules les mémoires dont thread_id stocké correspond exactement à cette unité d'exécution sont supprimées.
• 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 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 réussie efface l'état de sommaire d'unité d'exécution dérivée, de sorte que les appels de sommaire et de carte de contexte ultérieurs soient recréés à 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

Retourne une carte de contexte de type XML pour le thread.

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 : Carte contenant un sommaire du contexte d'unité d'exécution basé sur les messages les plus récents.
• Type de retour : str

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

méthode get_context_card_async (asynchrone)

Retourne 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 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 : Carte contenant un sommaire du contexte d'unité d'exécution basé sur les messages les plus récents.
• Type de retour : str

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 : Un message d'assistant contenant le sommaire ou une liste vide si le fil n'a 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

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 : Un message d'assistant contenant le sommaire ou une liste vide si le fil n'a 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