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.

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

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_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

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.