Magasins et schéma

Cette page présente les abstractions du fichier de base de données et les contrôles de schéma utilisés par le kit SDK de mémoire d'agent Oracle.

API de stockage

classe oracleagentmemory.core.OracleMemoryStore

Bases : IMemoryStore

Interface de banque commune utilisée par OracleAgentMemory.

Une implémentation de magasin est responsable de la persistance des enregistrements de texte et de l'exécution de recherches de similarité sur ces enregistrements. Les points d'entrée synchrones et asynchrones sont définis de sorte que les API de niveau supérieur peuvent afficher les surfaces synchrones/asynchrones correspondantes sans dupliquer la logique propre au magasin.

méthode add

Ajoutez des enregistrements au magasin.

• Paramètres:
  • contents list[str | None] – Enregistrez la charge utile pour la persistance. Les valeurs de texte sont également utilisées pour l'intégration, sauf si index_texts ou embeddings sont fournis. Lorsqu'une valeur de texte est None, les implémentations peuvent revenir à metadata["content"]. Les chaînes vides explicites sont conservées.
  • record_type str – Type d'enregistrement logique à créer, par exemple "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile".
  • index_texts list[str] – Charge utile alternative facultative utilisée uniquement pour l'intégration/indexation. Lorsqu'elle est fournie, doit correspondre aux entrées de texte.
  • embeddings list[list[float]] | list[ndarray] : vecteurs d'intégration précalculés facultatifs alignés sur les entrées de texte. Lorsqu'il est fourni, le magasin doit utiliser ces vecteurs directement au lieu d'appeler son intégrateur. S'il n'est pas fourni, le magasin doit avoir un intégrateur attaché, sinon une erreur sera générée.
  • record_ids str | None | list[str | None] : identificateurs invisibles par l'appelant (facultatif). Une seule chaîne peut être utilisée pour les insertions d'un enregistrement, tandis que les listes doivent s'aligner sur les entrées de texte. Les identificateurs générés sont renvoyés lorsque ce champ est omis.
  • thread_ids str | None | list[str | None] – Identificateurs de thread facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • user_ids str | None | list[str | None] – Identificateurs utilisateur facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • agent_ids str | None | list[str | None] : identificateurs d'agent facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • rôles str | None | list[str | None] : rôles de message facultatifs tels que "user" ou "assistant". Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées. Utilisé uniquement si record_type est "message".
  • timestamps str | None | list[str | None] : horodatages d'événement facultatifs à conserver avec les enregistrements. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – Dictionnaires de métadonnées fournis par l'appelant facultatifs. Les métadonnées peuvent inclure "content" en tant que source de secours lorsqu'une valeur de texte est omise plutôt que définie explicitement sur "".
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Type de retour : list[str]

Remarques

Utilisez add_batches() lorsque l'appelant comporte déjà un ou plusieurs objets PendingRecordBatch.

• Retours : Identificateurs des enregistrements insérés, dans le même ordre logique que l'entrée.
• Type de retour : List[str]
• Paramètres:
  • contenu list[str | None]
  • record_type str
  • textes_index list[str]
  • embarquements list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_agent (résumé)

Ajoutez un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur stable du profil d'agent.
  • information str : texte de forme libre décrivant l'agent.
• Retours : Identifiant de l'enregistrement de profil d'agent créé.
• Type de retour : str

method add_async (async)

Ajoutez de manière asynchrone des enregistrements orientés ligne au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add().

• Paramètres:
  • contenu list[str | None]
  • record_type str
  • textes_index list[str]
  • embarquements list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Type de retour : list[str]

méthode add_batches

Ajoutez des lots logiques préparés par l'appelant au magasin.

• Paramètres:
  • batches list[PendingRecordBatch] : lots logiques entièrement préparés pour persistance. Chaque lot doit contenir ses propres champs par enregistrement, tels que record_type, les valeurs de portée, les rôles, les horodatages et les métadonnées.
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Retours : Identifiants pour les enregistrements insérés, dans le même ordre logique que les lots et lignes d'entrée.
• Type de retour : List[str]

Exemples 

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (async)

Ajoutez de manière asynchrone des lots logiques préparés par l'appelant au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add_batches().

• Paramètres:
  • batchs list[PendingRecordBatch]
  • store_kwargs Any
• Type de retour : list[str]

method add_user (résumé)

Ajouter un enregistrement de profil utilisateur.

• Paramètres:
  • user_id str – Identificateur stable du profil utilisateur.
  • information str – Texte de forme libre décrivant l'utilisateur.
• Retours : Identifiant de l'enregistrement de profil utilisateur créé.
• Type de retour : str

method delete (résumé)

Supprimer un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à supprimer.
  • record_id str – Identifiant de l'enregistrement à supprimer.
  • cascade bool : lorsque True, appliquez tout comportement de suppression en cascade pris en charge par le magasin pour les cibles de niveau supérieur demandées dans la même opération de suppression. Il est principalement utilisé pour les cibles telles que les profils d'acteur qui possèdent des enregistrements de portée supplémentaires. Par exemple, une cascade de profils utilisateur ou d'agents peut supprimer les threads propriétaires eux-mêmes, les messages de portée thread et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée acteur directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Pour les suppressions de profil d'acteur, ce nettoyage ciblé peut toujours être exécuté lorsque la ligne de profil correspondante est déjà absente.
• Retours : nombre d'enregistrements de niveau supérieur demandés supprimés, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

method delete_thread (résumé)

Supprimer un thread et les données stockées associées.

• Paramètres : thread_id str – Identificateur du thread à enlever.
• Retours : nombre d'enregistrements de thread supprimés, généralement 0 ou 1.
• Type de retour : int

Remarques

Il s'agit de l'opération de niveau magasin permettant de supprimer un thread et les enregistrements de niveau thread gérés par le magasin. Préférez la suppression de thread lorsque les exigences de conservation appellent la suppression des messages source et des données de mémoire dérivées de portée thread, car les suppressions au niveau message n'impliquent pas la suppression des enregistrements dérivés conservés séparément.

method get (résumé)

Extraire un enregistrement stocké par type et identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à extraire.
  • record_id str – Identificateur de l'enregistrement à extraire.
• Retours : enregistrement stocké trouvé, sinon None.
• Type de retour : Enregistrement | Aucun

method list (résumé)

Répertoriez les enregistrements stockés pour un type d'enregistrement.

• Paramètres:
  • record_type str – Type d'enregistrement logique à énumérer.
  • limit int | None : nombre maximal facultatif d'enregistrements les plus récents à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont thread_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont user_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont agent_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
• Retours : Enregistrements classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : Liste[Enregistrement]

method list_thread_messages (résumé)

Répertoriez l'historique des messages stockés pour un thread.

• Paramètres:
  • thread_id str – Identificateur du thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à inclure. Lorsqu'il est omis, tous les messages stockés pour le thread sont renvoyés.
• Retours : Enregistrements de message classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : List[MessageRecord]

method search (résumé)

Rechercher des enregistrements par similarité.

• Paramètres:
  • query str | None : requête en langage naturel. Doit être fourni lorsque query_vector est omis.
  • query_vector list[float] | None : intégration de requête précalculée facultative. Vous devez fournir exactement l'une des options query et query_vector.
  • k int – Nombre maximal de résultats à renvoyer. Les valeurs explicites doivent être au moins 1.
  • thread_id str | None – Portée de thread facultative.
  • user_id str | None : filtres de portée utilisateur et agent facultatifs.
  • agent_id str | None : filtres de portée utilisateur et agent facultatifs.
  • exact_user_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • exact_agent_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • exact_thread_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • record_types set[str] | None – Ensemble facultatif de types d'enregistrement à inclure.
  • metadata_filter dict[str, Any] | None : mappage partiel de métadonnées facultatif. Un enregistrement correspond uniquement lorsque ses métadonnées stockées contiennent toutes les clés et valeurs demandées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs de liste sont mises en correspondance par égalité exacte plutôt que par correspondance de sous-ensemble récursive. Par conséquent, l'ordre et la longueur de la liste doivent également correspondre.
• Renvoie : paires (record, distance) triées par distance croissante.
• Type de retour : list[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

Exemples 

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

Filtrer sur une valeur de métadonnées scalaire :

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtrer sur les métadonnées imbriquées :

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Faites correspondre exactement une valeur de liste, y compris l'ordre :

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

method search_async (async)

Recherche asynchrone d'enregistrements par similarité vectorielle.

• Paramètres:
  • query str | None : même texte de requête accepté par search.
  • k int : nombre de résultats maximal identique accepté par search. Les valeurs explicites doivent être au moins 1.
  • query_vector list[float] | None – Même intégration de requête précalculée facultative acceptée par search.
  • thread_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • user_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • agent_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • exact_user_match bool – Les mêmes indicateurs de correspondance exacte acceptés par search.
  • exact_agent_match bool : indicateurs de correspondance exacte acceptés par search.
  • exact_thread_match bool : indicateurs de correspondance exacte acceptés par search.
  • record_types set[str] | None – Même filtre facultatif de type d'enregistrement accepté par search.
• Renvoie : paires (record, distance) renvoyées par l'appel search sous-jacent.
• Type de retour : List[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

method update (résumé)

Mettre à jour le contenu des enregistrements stockés, les données d'intégration ou les métadonnées.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à mettre à jour.
  • record_id str – Identifiant de l'enregistrement à mettre à jour.
  • text str | None : contenu de remplacement facultatif. Transmettez None pour effacer explicitement le texte stocké lorsque le magasin le prend en charge. Les magasins peuvent également effacer l'état sémantique associé et rejeter les mises à jour non NULL index_text ou embedding en conflit dans le même appel. Omettez l'argument pour laisser le contenu inchangé.
  • index_text str | None : charge utile facultative d'intégration uniquement utilisée pour recalculer le vecteur stocké sans modifier le texte persistant.
  • embedding list[float] | ndarray | None : vecteur d'intégration précalculé facultatif. Lorsqu'elle est fournie, elle est utilisée directement et aucun appel d'intégration n'est effectué. Transmettez None pour effacer explicitement l'intégration stockée lorsque l'emplacement de stockage la prend en charge.
  • metadata dict[str, Any] | None – Mappage de métadonnées de remplacement facultatif. Transmettez None pour effacer les métadonnées lorsque la banque les prend en charge.
• Retours : nombre d'enregistrements mis à jour, généralement 0 ou 1. Renvoie 0 lorsqu'aucun enregistrement stocké ne correspond à l'identificateur logique demandé.
• Type de retour : int
• Elèves : ValueError – Si la charge utile de mise à jour n'est pas valide pour le magasin, par exemple en omettant tous les champs facultatifs ou en fournissant des arguments sémantiques contradictoires.

Banque Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases : OracleMemoryStore

Persistance basée sur la base de données pour les messages, les mémoires et les profils d'acteur.

Créez une banque Oracle DB.

• Paramètres:
  • embedder IEmbedder | None – Embedder utilisé pour les types d'enregistrement vectorisés. Peut être None lorsque les appelants fournissent toujours des vecteurs précalculés dans add, update et search.
  • pool Any : connexion ou pool Oracle DB. La transmission d'une connexion brute active le mode de session unique pour cette instance de stockage : les appels de stockage simultanés sont sérialisés localement afin de préserver les hypothèses de verrouillage de ligne et de transaction utilisées par les opérations d'écriture. Utilisez un pool de connexions pour les demandes simultanées.
  • schema_policy SchemaPolicy | str – Mode de configuration du schéma. Exige par défaut un schéma géré existant et à jour et n'effectue aucune modification LDD. Utilisez SchemaPolicy.CREATE_IF_NECESSARY pour remplir les objets manquants ou SchemaPolicy.RECREATE pour supprimer et recréer des objets gérés.
  • vector_dim int : dimension d'intégration pour la création de schéma lors de la création de colonnes VECTOR.
  • table_name_prefix str : préfixe facultatif ajouté aux noms de table/index gérés.

méthode add

Ajoutez des enregistrements au magasin.

• Paramètres:
  • contents list[str | None] – Enregistrez la charge utile pour la persistance. Les valeurs de texte sont également utilisées pour l'intégration, sauf si index_texts ou embeddings sont fournis. Lorsqu'une valeur de texte est None, les implémentations peuvent revenir à metadata["content"]. Les chaînes vides explicites sont conservées.
  • record_type str – Type d'enregistrement logique à créer, par exemple "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile".
  • index_texts list[str] – Charge utile alternative facultative utilisée uniquement pour l'intégration/indexation. Lorsqu'elle est fournie, doit correspondre aux entrées de texte.
  • embeddings list[list[float]] | list[ndarray] : vecteurs d'intégration précalculés facultatifs alignés sur les entrées de texte. Lorsqu'il est fourni, le magasin doit utiliser ces vecteurs directement au lieu d'appeler son intégrateur. S'il n'est pas fourni, le magasin doit avoir un intégrateur attaché, sinon une erreur sera générée.
  • record_ids str | None | list[str | None] : identificateurs invisibles par l'appelant (facultatif). Une seule chaîne peut être utilisée pour les insertions d'un enregistrement, tandis que les listes doivent s'aligner sur les entrées de texte. Les identificateurs générés sont renvoyés lorsque ce champ est omis.
  • thread_ids str | None | list[str | None] – Identificateurs de thread facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • user_ids str | None | list[str | None] – Identificateurs utilisateur facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • agent_ids str | None | list[str | None] : identificateurs d'agent facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • rôles str | None | list[str | None] : rôles de message facultatifs tels que "user" ou "assistant". Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées. Utilisé uniquement si record_type est "message".
  • timestamps str | None | list[str | None] : horodatages d'événement facultatifs à conserver avec les enregistrements. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – Dictionnaires de métadonnées fournis par l'appelant facultatifs. Les métadonnées peuvent inclure "content" en tant que source de secours lorsqu'une valeur de texte est omise plutôt que définie explicitement sur "".
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Type de retour : list[str]

Remarques

Utilisez add_batches() lorsque l'appelant comporte déjà un ou plusieurs objets PendingRecordBatch.

• Retours : Identificateurs des enregistrements insérés, dans le même ordre logique que l'entrée.
• Type de retour : List[str]
• Paramètres:
  • contenu list[str | None]
  • record_type str
  • textes_index list[str]
  • embarquements list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

method add_async (async)

Ajoutez de manière asynchrone des enregistrements orientés ligne au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add().

• Paramètres:
  • contenu list[str | None]
  • record_type str
  • textes_index list[str]
  • embarquements list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Type de retour : list[str]

méthode add_batches

Ajoutez des lots logiques préparés par l'appelant au magasin.

• Paramètres:
  • batches list[PendingRecordBatch] : lots logiques entièrement préparés pour persistance. Chaque lot doit contenir ses propres champs par enregistrement, tels que record_type, les valeurs de portée, les rôles, les horodatages et les métadonnées.
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Retours : Identifiants pour les enregistrements insérés, dans le même ordre logique que les lots et lignes d'entrée.
• Type de retour : List[str]

Exemples 

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

method add_batches_async (async)

Ajoutez de manière asynchrone des lots logiques préparés par l'appelant au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add_batches().

• Paramètres:
  • batchs list[PendingRecordBatch]
  • store_kwargs Any
• Type de retour : list[str]

méthode add_agent

Ajoutez un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur d'agent.
  • information str : informations de forme libre sur l'agent. Ce texte est stocké en tant que contenu de profil et utilisé pour créer la ligne d'intégration de profil dans RECORD_CHUNKS.
• Retours : Identificateur de l'enregistrement de profil d'agent inséré.
• Type de retour : str

Remarques

La portée des enregistrements de profil d'agent n'est pas définie. L'identificateur d'enregistrement public inséré est la même valeur transmise que agent_id.

Exemples 

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

méthode add_user

Ajouter un enregistrement de profil utilisateur.

• Paramètres:
  • user_id str : identificateur utilisateur.
  • information str : informations de forme libre sur l'utilisateur. Ce texte est stocké en tant que contenu de profil et utilisé pour créer la ligne d'intégration de profil dans RECORD_CHUNKS.
• Retours : Identifiant de l'enregistrement de profil utilisateur inséré.
• Type de retour : str

Remarques

Les enregistrements de profil utilisateur n'ont pas de portée. L'identificateur d'enregistrement public inséré est la même valeur transmise que user_id.

Exemples 

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

méthode delete

Supprimez une ligne gérée et ses lignes de bloc par identificateur.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement à supprimer. Les types pris en charge sont "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" et "agent_profile".
  • record_id str – Identificateur à supprimer.
  • cascade bool : lorsque True, développez les cibles de niveau supérieur prises en charge, telles que les profils d'acteur, jusqu'à leurs lignes enfant ciblées dans la même transaction. Pour une cible de profil utilisateur ou de profil d'agent, cela supprime d'abord les lignes de thread détenues, ce qui enlève leurs lignes de message de niveau thread et de table de mémoire, puis supprime tous les messages de niveau acteur directs restants et les lignes de type mémoire (memory, guideline, fact, preference). Ce nettoyage ciblé s'exécute quand la ligne de profil correspondante est déjà absente.
• Retours : nombre de cibles de niveau supérieur demandées enlevées, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

Remarques

L'opération s'exécute dans une transaction. Lorsque cascade est activé pour une cible de niveau supérieur prise en charge, la suppression de profil et toutes les suppressions enfant ciblées sont validées ou annulées ensemble.

Exemples 

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

méthode delete_thread

Supprimer un thread et ses lignes stockées associées.

• Paramètres : thread_id str : identificateur de thread dont les lignes doivent être enlevées, notamment la ligne de thread, les lignes enfant dépendantes et le nettoyage explicite des lignes de segment.
• Renvoie : nombre de lignes de thread supprimées (0 ou 1).
• Type de retour : int

Remarques

Utilisez cette opération lorsque vous avez besoin d'un nettoyage en cascade de niveau thread. Dans l'emplacement de stockage sauvegardé par la base de données, la suppression du thread enlève la ligne de thread gérée ainsi que les lignes de message et de mémoire associées, ainsi que les lignes de bloc d'enregistrement tenues à jour pour extraction. Elle est plus large qu'une suppression de niveau message, qui supprime uniquement la ligne de message brut. La suppression de thread enlève les lignes de mémoire et de message dépendantes référencées dans THREAD ainsi que les lignes RECORD_CHUNKS correspondantes dans la même transaction.

Exemples 

store.delete_thread("c1")
0

method get

Extraire un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement résolu en ligne gérée, telle que "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile".
  • record_id str : identificateur à rechercher.
• Retours : enregistrement rempli avec des métadonnées décodées lorsqu'elles sont trouvées, sinon None.
• Type de retour : Enregistrement | Aucun

Exemples 

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

méthode list

Enumérer les enregistrements persistants pour un type d'enregistrement.

• Paramètres:
  • record_type str – Libellé du type d'enregistrement (par exemple, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile").
  • limit int | None – Nombre maximum d'enregistrements à renvoyer (facultatif). Lorsqu'il est omis, le magasin utilise sa limite de liste par défaut. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont thread_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont user_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont agent_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements sans métadonnées stockées sont renvoyés. Lorsqu'elle est définie sur un dict, les métadonnées stockées doivent contenir toutes les clés et valeurs demandées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs de liste sont mises en correspondance par égalité exacte plutôt que par correspondance de sous-ensemble récursive. Par conséquent, l'ordre et la longueur de la liste doivent également correspondre.
• Retours : Enregistrements triés par ordre d'insertion.
• Type de retour : list[Enregistrement]

Remarques

"user_profile" et "agent_profile" sont des types d'enregistrement non ciblés. Pour ces types d'enregistrement, thread_id, user_id et agent_id sont ignorés et l'identité de l'acteur reste dans record.id.

Exemples 

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

méthode list_thread_messages

Renvoyer les messages persistants pour un thread.

• Paramètres:
  • thread_id str : identificateur de thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à renvoyer.
• Retours : Enregistrements de message triés par ordre d'insertion.
• Type de retour : list[MessageRecord]

Exemples 

store.list_thread_messages("c1")
[]

méthode search

Rechercher des enregistrements par similarité.

• Paramètres:
  • query str | None : requête en langage naturel. Doit être fourni lorsque query_vector est omis.
  • query_vector list[float] | None : intégration de requête précalculée facultative. Vous devez fournir exactement l'une des options query et query_vector.
  • k int – Nombre maximal de résultats à renvoyer. Les valeurs explicites doivent être au moins 1.
  • thread_id str | None : identificateur de portée de thread facultatif. exact_thread_match=False laisse la dimension de thread sans contrainte. exact_thread_match=True correspond exactement au paramètre thread_id fourni. Si la valeur est thread_id=None, elle correspond uniquement aux enregistrements non ciblés sur la dimension de thread.
  • user_id str | None : identificateurs de portée utilisateur et agent facultatifs. L'indicateur exact_*_match=False correspondant laisse cette dimension sans contrainte. exact_*_match=True correspond exactement à l'ID fourni. Si l'ID est None, il correspond uniquement aux enregistrements non ciblés sur cette dimension.
  • agent_id str | None : identificateurs de portée d'agent et d'utilisateur facultatifs. L'indicateur exact_*_match=False correspondant laisse cette dimension sans contrainte. exact_*_match=True correspond exactement à l'ID fourni. Si l'ID est None, il correspond uniquement aux enregistrements non ciblés sur cette dimension.
  • exact_user_match bool – Indique si chaque identificateur de portée doit correspondre exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • exact_agent_match bool – Indique si chaque identificateur de portée doit être mis en correspondance exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • exact_thread_match bool : indique si chaque identificateur de portée doit être mis en correspondance exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • record_types set[str] | None – Ensemble facultatif de types d'enregistrement recherchables à inclure. Lorsqu'elle est omise, la recherche de base de données couvre les messages, les lignes de la table mémoire et les profils d'acteur. Les profils d'acteur fournissent leur charge utile information, tandis que les lignes de message et de mémoire fournissent leur charge utile content. Au cours de la recherche, les types d'enregistrement de profil utilisent leur identifiant d'acteur pour la dimension de portée applicable, tandis que les dimensions de portée restantes se comportent comme None.
  • metadata_filter dict[str, Any] | None : mappage partiel de métadonnées facultatif. Un enregistrement correspond uniquement lorsque ses métadonnées stockées contiennent toutes les clés et valeurs demandées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs de liste sont mises en correspondance par égalité exacte plutôt que par correspondance de sous-ensemble récursive. Par conséquent, l'ordre et la longueur de la liste doivent également correspondre.
• Renvoie : paires (record, distance) triées par distance croissante.
• Type de retour : list[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

Exemples 

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

Filtrer sur une valeur de métadonnées scalaire :

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Filtrer sur les métadonnées imbriquées :

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Faites correspondre exactement une valeur de liste, y compris l'ordre :

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

method search_async (async)

Recherche asynchrone d'enregistrements par similarité vectorielle.

• Paramètres:
  • query str | None : même texte de requête accepté par search.
  • k int : nombre de résultats maximal identique accepté par search. Les valeurs explicites doivent être au moins 1.
  • query_vector list[float] | None – Même intégration de requête précalculée facultative acceptée par search.
  • thread_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • user_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • agent_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • exact_user_match bool – Les mêmes indicateurs de correspondance exacte acceptés par search.
  • exact_agent_match bool : indicateurs de correspondance exacte acceptés par search.
  • exact_thread_match bool : indicateurs de correspondance exacte acceptés par search.
  • record_types set[str] | None – Même filtre facultatif de type d'enregistrement accepté par search.
• Renvoie : paires (record, distance) renvoyées par l'appel search sous-jacent.
• Type de retour : List[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

méthode update

Mettre à jour le contenu des enregistrements stockés, les incorporations de bloc et les valeurs de métadonnées.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement de la ligne en cours de modification (par exemple, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile")
  • record_id str – Identificateur de la ligne stockée à mettre à jour.
  • text str | None – Texte de remplacement facultatif conservé dans la colonne content. Transmettez None pour effacer le texte stocké et effacer l'intégration stockée. Transmettez uniquement None ou les arguments sémantiques omis dans le même appel. Transmettez "" pour conserver le contenu vide explicite tout en effaçant l'intégration de blocs pour cet enregistrement. Lorsqu'il est omis, le contenu existant reste inchangé.
  • index_text str | None : charge utile d'intégration uniquement (facultatif). Lorsqu'elle est omise, text est imbriqué.
  • embedding list[float] | ndarray | None : vecteur d'intégration précalculé facultatif. Lorsqu'elle est fournie, elle est utilisée directement et aucun appel d'intégration n'est effectué. Transmettez None pour effacer l'intégration stockée.
  • metadata dict[str, Any] | None – Mise en correspondance de métadonnées facultative sérialisée avec JSON et stockée dans metadata.
• Retours : nombre de lignes mises à jour (0 ou 1). Renvoie 0 lorsqu'aucun enregistrement logique ne correspond à record_type et record_id.
• Type de retour : int
• Elèves : ValueError – Si record_type n'est pas pris en charge, si aucune charge utile de mise à jour n'est fournie ou si les arguments de mise à jour sémantique sont incompatibles.

Exemples 

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

Stratégie de schéma

classe oracleagentmemory.core.SchemaPolicy

Bases : str, Enum

Stratégie de création de schéma pour les banques Oracle DB.

EXIGER_EXISTANT

Vérifiez que le schéma géré complet existe déjà et qu'il est à jour. Ne créez ni ne modifiez des objets de base de données.

CREATE_IF_EMPTY

S'il n'existe aucun objet géré, initialisez le schéma. Si des objets existent déjà, vous devez disposer d'un schéma géré complet et à jour.

CRÉER_SI_NÉCESSAIRE

Créez uniquement les objets gérés manquants, y compris les métadonnées.

RECRÉER

Supprimez et recréez tous les objets de schéma gérés. C'est destructeur.