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.

Notes

Créez une instance OracleThread.

Exemples

from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c4",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

méthode add_image

Conserver une image associée à ce thread.

description est stocké en tant que texte recherchable de l'image. Lorsqu'il est omis ou None, un LLM attaché génère une légende. Les valeurs de portée omises héritent des identificateurs d'utilisateur, d'agent et de thread correspondants de ce thread.

method add_image_async (async)

Conserver une image associée à ce thread de manière asynchrone.

description est stocké en tant que texte recherchable de l'image. Lorsqu'il est omis ou None, un LLM attaché génère une légende. Les valeurs de portée omises héritent des identificateurs d'utilisateur, d'agent et de thread correspondants de ce thread.

méthode add_memory

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

Exemples

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

method add_memory_async (async)

Ajoutez une entrée de mémoire manuelle et indexez-la de manière asynchrone.

Exemples

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

méthode add_messages

Ajoutez des messages au thread et indexez-les.

En mode d'extraction en arrière-plan, cette méthode est renvoyée après l'insertion des messages bruts et la tentative d'extraction en arrière-plan en arrière-plan.

Les messages bruts sont stockés avant l'extraction automatique dans les deux modes. En cas d'échec de l'extraction ultérieure ou du stockage en mémoire dérivée, les messages bruts restent stockés alors que des mémoires dérivées ou des mises à jour récapitulatives peuvent être manquantes.

Notes

Dans MemoryExtractionMode.BACKGROUND, les messages bruts sont conservés avant que les mémoires extraites ne soient stockées. Si l'extraction en arrière-plan n'est pas en file d'attente, ou si une attente de capacité de file d'attente configurée atteint son délai d'attente, les messages bruts insérés restent stockés et l'appel continue sans mémoires extraites ou soulève TimeoutError, selon background_extraction_queue_full_behavior.

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.

En mode d'extraction en arrière-plan, cette méthode est renvoyée après l'insertion des messages bruts et la tentative d'extraction en arrière-plan en arrière-plan.

Les messages bruts sont stockés avant l'extraction automatique dans les deux modes. En cas d'échec de l'extraction ultérieure ou du stockage en mémoire dérivée, les messages bruts restent stockés alors que des mémoires dérivées ou des mises à jour récapitulatives peuvent être manquantes.

Dans MemoryExtractionMode.BACKGROUND, les messages bruts sont conservés avant que les mémoires extraites ne soient stockées. Si l'extraction en arrière-plan n'est pas en file d'attente, ou si une attente de capacité de file d'attente configurée atteint son délai d'attente, les messages bruts insérés restent stockés et l'appel continue sans mémoires extraites ou soulève TimeoutError, selon background_extraction_queue_full_behavior.

méthode delete_image

Supprimez une image appartenant à ce thread.

method delete_image_async (async)

Supprimez une image appartenant à ce thread de manière asynchrone.

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.

Notes

Avant de supprimer l'enregistrement, cette méthode attend une extraction en arrière-plan antérieure acceptée pour ce thread via le composant de mémoire de l'agent attaché. Il n'attend pas que le travail soit accepté après le début de l'attente ou que le travail soit démarré par un autre composant ou processus.

Exemples

thread.delete_memory("456")
0

method delete_memory_async (async)

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 de manière asynchrone.

Notes

Cette méthode suit le comportement d'attente et de simultanéité d'extraction en arrière-plan documenté par delete_memory().

Exemples

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

méthode delete_message

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

Notes

Avant de supprimer le message, cette méthode attend une extraction en arrière-plan antérieure acceptée pour ce thread via le composant de mémoire de l'agent attaché. Il n'attend pas que le travail soit accepté après le début de l'attente ou que le travail soit démarré par un autre composant ou processus.

La suppression d'un message supprime uniquement l'enregistrement de message brut. Les mémoires dérivées ne sont pas supprimées car nous ne suivons pas encore les mémoires extraites provenant de quel message, de sorte qu'elles peuvent rester consultables ou encore 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

method delete_message_async (async)

Supprimer un enregistrement de message de ce thread exact par identifiant de manière asynchrone.

Notes

Cette méthode suit le comportement d'attente et de simultanéité d'extraction en arrière-plan documenté par delete_message().

La suppression d'un message supprime uniquement l'enregistrement de message brut. Les mémoires dérivées ne sont pas supprimées car nous ne suivons pas encore les mémoires extraites provenant de quel message, de sorte qu'elles peuvent rester consultables ou encore 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

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

Supprimez une relation détenue par un thread par ID ou complétez le tuple d'adresse.

Les sélecteurs d'adresse doivent utiliser l'orientation source-cible stockée.

Exemples

thread.delete_record_link(relation_id="relation-id")
1

Supprimez de manière asynchrone une relation appartenant à ce thread.

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.

Notes

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
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async (async)

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

Exemples

import asyncio
card = asyncio.run(thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
))
len(card.relevant_results or []) <= 5
True

méthode get_message

Renvoyer un message appartenant à ce thread.

Les parties d'image sont renvoyées avec leurs identificateurs et descriptions par défaut. Transmettez included_image_ids pour charger les octets des parties d'image sélectionnées. Les identificateurs non liés sont ignorés.

method get_message_async (async)

Renvoyer un message appartenant au thread de manière asynchrone.

included_image_ids sélectionne éventuellement les parties d'image attachées dont les octets doivent être chargés ; omis ou None renvoie uniquement les métadonnées d'image.

méthode get_messages

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

Exemples

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

method get_messages_async (async)

Obtenez les messages non traités à partir du thread, tels qu'ils ont été ajoutés avec add_messages de manière asynchrone.

Exemples

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

méthode get_summary

Renvoie un récapitulatif du sujet de discussion.

Une demande de thread complet réutilise ou actualise le récapitulatif durable. Une demande avec except_last récapitule ce préfixe sans modifier le récapitulatif complet durable.

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

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 du thread.

Une demande de thread complet réutilise ou actualise le récapitulatif durable. Une demande avec except_last récapitule ce préfixe sans modifier le récapitulatif complet durable.

Créez une relation dirigée entre deux enregistrements appartenant à ce thread.

Actuellement, les deux adresses doivent être des enregistrements de type mémoire : "memory", "fact", "guideline" ou "preference". Les types de relation intégrés sont "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") et "duplicates". "contradicts" et "duplicates" utilisent le même libellé à l'envers.

Les deux adresses doivent appartenir à ce thread exact. Une seule orientation peut être stockée pour une paire d'adresses. opposite_relation_type nomme la relation lors de l'acheminement de la cible vers la source. Par exemple, new "supersedes" old devient old "is_superseded_by" new dans cette direction.

Exemples

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Créez de manière asynchrone une relation entre les enregistrements appartenant à ce thread.

Actuellement, les deux adresses doivent être des enregistrements de type mémoire : "memory", "fact", "guideline" ou "preference". Les types de relation intégrés sont "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") et "duplicates". "contradicts" et "duplicates" utilisent le même libellé à l'envers.

méthode list_images

Répertorier les enregistrements d'image détenus par ce thread.

Les enregistrements renvoyés contiennent des métadonnées d'image par défaut. Les octets bruts sont chargés uniquement lorsque include_bytes=True et image_id sont fournis.

method list_images_async (async)

Répertorier les enregistrements d'image appartenant à ce thread de manière asynchrone.

Les enregistrements renvoyés contiennent des métadonnées d'image par défaut. Les octets bruts sont chargés uniquement lorsque include_bytes=True et image_id sont fournis. La portée de ce thread est appliquée automatiquement.

Rechercher de manière synchrone les enregistrements pertinents pour une requête.

Notes

Les champs de portée omis héritent de la portée de recherche par défaut de ce thread : correspondance exacte entre l'utilisateur et l'agent, plus les valeurs user_id, agent_id et thread_id en cours de ce thread. La recherche de thread par défaut laisse intentionnellement exact_thread_match=False, de sorte qu'elle peut renvoyer les enregistrements pertinents d'autres threads pour le même utilisateur/agent. Transmettez exact_thread_match=True pour limiter les résultats au thread en cours. Les valeurs de portée None explicites suivent toujours les règles de correspondance exacte résolues : exact_*_match=False laisse cette dimension sans contrainte, tandis que exact_*_match=True correspond uniquement aux valeurs None stockées.

Les valeurs max_results explicites doivent être au moins 1. Si vous omettez l'argument, la valeur par défaut de 10 est utilisée. Limite supérieure : l'appel peut renvoyer moins de résultats max_results lorsque les filtres sont trop restrictifs, lorsqu'il existe moins d'enregistrements correspondants ou en raison d'un comportement de recherche propre à l'implémentation.

method search_async (async)

Rechercher de manière asynchrone les enregistrements pertinents pour une requête.

Notes

Les champs de portée omis héritent de la portée de recherche par défaut de ce thread : correspondance exacte entre l'utilisateur et l'agent, plus les valeurs user_id, agent_id et thread_id en cours de ce thread. La recherche de thread par défaut laisse intentionnellement exact_thread_match=False, de sorte qu'elle peut renvoyer les enregistrements pertinents d'autres threads pour le même utilisateur/agent. Transmettez exact_thread_match=True pour limiter les résultats au thread en cours. Les valeurs de portée None explicites suivent toujours les règles de correspondance exacte résolues : exact_*_match=False laisse cette dimension sans contrainte, tandis que exact_*_match=True correspond uniquement aux valeurs None stockées.

Les valeurs max_results explicites doivent être au moins 1. Si vous omettez l'argument, la valeur par défaut de 10 est utilisée. Limite supérieure : l'appel peut renvoyer moins de résultats max_results lorsque les filtres sont trop restrictifs, lorsqu'il existe moins d'enregistrements correspondants ou en raison d'un comportement de recherche propre à l'implémentation.

méthode update_image

Mettez à jour une image appartenant à ce thread.

Omettez image pour conserver les octets existants. Si image est fourni, mime_type doit l'être. Omettez description pour conserver la description existante. Transmettez None pour générer une nouvelle description avec le LLM configuré ; une description non NULL la remplace directement. L'expiration d'une image jointe à un message doit être modifiée via update_message().

method update_image_async (async)

Mettez à jour une image appartenant à ce thread de manière asynchrone.

Omettez image pour conserver les octets existants. Si image est fourni, mime_type doit l'être. Omettez description pour conserver la description existante. Transmettez None pour générer une nouvelle description avec le LLM configuré ; une description non NULL la remplace directement. Les paramètres de métadonnées, d'horodatage et d'expiration sont mis à jour lorsqu'ils sont fournis. L'expiration d'une image jointe à un message doit être modifiée via update_message_async().

méthode update_memory

Mettre à jour un enregistrement de type mémoire appartenant à ce thread exact.

method update_memory_async (async)

Mettre à jour de manière asynchrone un enregistrement de type mémoire appartenant à ce thread exact.

Exemples

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

méthode update_message

Mettre à jour un enregistrement de message brut appartenant à ce thread exact.

Notes

Les champs omis sont préservés de l'enregistrement stocké. Le rôle stocké et l'horodatage restent inchangés. La modification du contenu met à jour l'historique des messages bruts et, lorsque l'extraction automatique est activée, le kit SDK peut extraire de nouveau les mémoires du message modifié et de l'historique précédent. En mode INLINE, cette extraction se termine avant que cette méthode ne soit renvoyée. En mode BACKGROUND, cette méthode renvoie une fois la mise à jour du message brut réussie et l'extraction en arrière-plan tentée. Ce travail de suivi n'affecte pas la fréquence d'extraction normale utilisée par les appels add_messages() ultérieurs. Les mémoires extraites existantes restent en place tandis que les mémoires nouvellement extraites du contenu modifié peuvent être ajoutées. Etant donné que la mise à jour du message brut et toute écriture de mémoire extraite ultérieure ne se produisent pas de manière atomique, les mémoires extraites peuvent toujours refléter le contenu du message précédent si le travail en arrière-plan ne fait pas l'objet d'une file d'attente, si une attente de capacité de file d'attente configurée atteint son délai d'attente ou si le travail d'extraction ultérieur échoue. Notez également que les mémoires extraites existantes conservent leur expiration initiale lorsque la durée de vie d'un message source change.

Exemples

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async (async)

Mettre à jour un enregistrement de message brut appartenant à ce thread exact de manière asynchrone.

Notes

Les champs omis sont préservés de l'enregistrement stocké. Le rôle stocké et l'horodatage restent inchangés. La modification du contenu met à jour l'historique des messages bruts et, lorsque l'extraction automatique est activée, le kit SDK peut extraire de nouveau les mémoires du message modifié et de l'historique précédent. En mode INLINE, cette extraction se termine avant que cette méthode ne soit renvoyée. En mode BACKGROUND, cette méthode renvoie une fois la mise à jour du message brut réussie et l'extraction en arrière-plan tentée. Ce travail de suivi n'affecte pas la fréquence d'extraction normale utilisée par les appels add_messages() ultérieurs. Les mémoires extraites existantes restent en place tandis que les mémoires nouvellement extraites du contenu modifié peuvent être ajoutées. Etant donné que la mise à jour du message brut et toute écriture de mémoire extraite ultérieure ne se produisent pas de manière atomique, les mémoires extraites peuvent toujours refléter le contenu du message précédent si le travail en arrière-plan ne fait pas l'objet d'une file d'attente, si une attente de capacité de file d'attente configurée atteint son délai d'attente ou si le travail d'extraction ultérieur échoue. Notez également que les mémoires extraites existantes conservent leur expiration initiale lorsque la durée de vie d'un message source change.

Exemples

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

Mettez à jour une relation dont les adresses appartiennent à ce thread.

Les valeurs omises sont conservées. Lorsque relation_type passe à un type de relation de mémoire intégré, son libellé inverse fixe remplace opposite_relation_type.

Exemples

thread.update_record_link("relation-id", relation_type="supports")
1

Mettez à jour de manière asynchrone une relation dont les adresses appartiennent à ce thread.

méthode wait_for_memory_extraction

Attendez l'extraction de mémoire en arrière-plan précédente pour ce thread.

Cette méthode attend l'extraction en arrière-plan démarrée par les appels add_messages(), add_messages_async(), update_message() ou update_message_async() précédents sur ce thread via le même composant de mémoire d'agent. Si l'un de ces appels est déjà terminé, cette méthode inclut l'extraction qu'il commence avant d'attendre.

La méthode n'attend pas que l'extraction démarre après ce début d'attente, que l'extraction démarre par un autre composant de mémoire d'agent ou que l'extraction s'exécute dans un autre processus. Les échecs d'extraction sont comptabilisés comme terminés pour cette attente.

Exemples

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (async)

Attendez asynchrone l'extraction de mémoire en arrière-plan précédente.

Cette méthode suit le même comportement que wait_for_memory_extraction().

Exemples

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

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. La suppression de messages et de mémoire via un descripteur de thread attend une extraction en arrière-plan antérieure déjà acceptée par le client attaché pour ce thread. Il ne s'agit pas d'une barrière de simultanéité globale pour les autres instances client, processus ou travaux acceptés après le début de l'attente.

Messages et contenu des messages

classe oracleagentmemory.apis.message.Message

Bases : object

Message en mémoire partagé par les threads et les adaptateurs LLM.

classe oracleagentmemory.apis.message.MessageContent

Bases : ABC

Classe de base pour le contenu de message structuré.

classe oracleagentmemory.apis.message.TextContent

Bases : MessageContent

Partie de texte d'un message multimodal.

classe oracleagentmemory.apis.message.ImageContent

Bases : MessageContent

Partie d'une image dans un message multimodal.

classe oracleagentmemory.apis.message.ImageMimeType

Bases : str, Enum

Types MIME pris en charge pour le contenu d'image.

Les formats PNG et WebP animés ne sont pas pris en charge.

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'image/WEBP'

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é)

classe oracleagentmemory.core.contextcard.OracleContextCard

Bases : ContextCard

Carte de contexte renvoyée par un thread Oracle.

propriété content

Exemples

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

propriété formatted_content

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é)

classe oracleagentmemory.core.summary.OracleSummary

Bases : Summary

Récapitulatif renvoyé par un thread Oracle.

Exemples

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

propriété content

Exemples

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

propriété formatted_content

Exemples

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