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 add (résumé)

Intégrer et rendre persistants les enregistrements de texte.

• Paramètres:
  • contents list[str | None] : charge utile de type texte à stocker. Ces valeurs sont également utilisées comme charge utile d'intégration lorsque index_texts n'est pas fourni. Lorsqu'un élément est omis (None), stocke sa résolution à partir de la clé de métadonnées "content" lorsqu'elle est disponible ; sinon, le contenu vide est conservé.
  • record_type str – Libellé du type d'enregistrement pour les enregistrements stockés (par exemple, "message" ou "memory").
  • index_texts list[str] : charge utile d'intégration uniquement (facultatif) alignée sur contents.
  • embeddings list[list[float]] | list[ndarray] : vecteurs d'intégration précalculés facultatifs alignés sur contents. Lorsqu'ils sont fournis, les magasins utilisent ces vecteurs directement et n'appellent pas l'intégrateur.
  • record_ids str | None | list[str] | list[None] – ID d'enregistrement visibles par l'appelant (facultatif). Doit être entièrement fourni (un par texte) ou omis pour tous les textes. Les ID renvoyés correspondent à ces valeurs lorsqu'ils sont fournis.
  • thread_ids str | None | list[str | None] – Identificateurs de portée facultatifs stockés avec les enregistrements.
  • user_ids str | None | list[str | None] : identificateurs de portée facultatifs stockés avec les enregistrements.
  • agent_ids str | None | list[str | None] : identificateurs de portée facultatifs stockés avec les enregistrements.
  • rôles str | None | list[str | None] : rôle de discussion facultatif pour les enregistrements de message.
  • timestamps str | None | list[str | None] : horodatage facultatif ou horodatage par enregistrement.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None – Mapping de métadonnées facultatif ou mappings de métadonnées par enregistrement. Les métadonnées peuvent inclure "content" comme source de secours pour les valeurs de texte omises.
  • **store_kwargs (N'importe lequel) : options d'écriture propres au magasin transmises par des API de niveau supérieur.
• Retours : Insère des identificateurs pour chaque élément de contenu d'entrée. Elles correspondent à record_ids lorsqu'elles sont fournies ; dans le cas contraire, elles génèrent des identificateurs.
• Type de retour : list[str]

Exemples 

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

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 sauvegardée par la base de données pour les messages et les enregistrements de mémoire saisis.

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 à la mémoire.

• Paramètres:
  • contents list[str | None] : charge utile de type texte à stocker. Ces valeurs sont également utilisées pour calculer l'intégration, sauf si index_texts ou embeddings sont fournis. Lorsqu'un élément est omis (None), stocke sa résolution à partir de la clé de métadonnées "content" lorsqu'elle est disponible. Sinon, le contenu vide est conservé.
  • record_type str – Libellé de type d'enregistrement pour les enregistrements stockés (par exemple, "message", "memory", guideline, fact ou preference).
  • index_texts list[str] – Charge utile alternative facultative utilisée uniquement pour l'intégration/indexation. Lorsqu'elle est fournie, elle doit avoir la même longueur que contents.
  • embeddings list[list[float]] | list[ndarray] : vecteurs d'intégration précalculés facultatifs alignés sur contents. Lorsqu'ils sont fournis, les magasins doivent utiliser ces vecteurs directement et ne doivent pas appeler l'intégrateur. Lorsqu'il est omis, le magasin utilise l'intégrateur uniquement pour les charges utiles d'indexation non vides ; les chaînes vides explicites sont stockées sans intégration de blocs.
  • record_ids str | None | list[str] | list[None] – ID d'enregistrement visibles par l'appelant (facultatif). Doit être entièrement fourni (un par texte) ou omis pour tous les textes. Les ID renvoyés correspondent à ces valeurs lorsqu'ils sont fournis. Lorsqu'il est omis, le magasin génère des ID côté client.
  • thread_ids str | None | list[str | None] – Identificateurs de portée facultatifs stockés avec les enregistrements.
  • user_ids str | None | list[str | None] : identificateurs de portée facultatifs stockés avec les enregistrements.
  • agent_ids str | None | list[str | None] : identificateurs de portée facultatifs stockés avec les enregistrements.
  • rôles str | None | list[str | None] : rôle de discussion facultatif pour les enregistrements de message.
  • horodatages str | None | list[str | None] – Horodatages d'événement fournis par l'appelant en option.
  • 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" comme source de secours pour les valeurs de texte omises.
  • **store_kwargs (Any) : options d'écriture propres au magasin. Les clés prises en charge incluent actuellement batch_size pour le traitement par lots Oracle executemany.
• Retours : Insère des identificateurs pour chaque élément de contenu d'entrée. Elles correspondent à record_ids lorsqu'elles sont fournies ; sinon, elles stockent les ID générés par le retour.
• Type de retour : list[str]

Exemples 

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

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.
• Retours : Identificateur de l'enregistrement de profil d'agent inséré.
• Type de retour : str

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.
• Retours : Identifiant de l'enregistrement de profil utilisateur inséré.
• Type de retour : str

Exemples 

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

méthode delete

Supprimez une ligne d'enregistrement vectoriel gérée et ses lignes de bloc par identificateur.

• Paramètres:
  • record_type str : étiquette de type d'enregistrement dont la table gérée doit être ciblée, telle que "message", "memory", "guideline", "fact" ou "preference"
  • record_id str – Identificateur de la ligne à supprimer.
• Renvoie : nombre de lignes enlevées (0 lorsque l'identificateur est introuvable).
• Type de retour : int

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 d'enregistrement vectoriel et de bloc associées.

• Paramètres : thread_id str : identificateur de thread dont les lignes doivent être enlevées (y compris les lignes enfant supprimées en cascade).
• Renvoie : nombre de lignes de thread supprimées (0 ou 1).
• Type de retour : int

Exemples 

store.delete_thread("c1")
0

method get

Récupère un message ou une mémoire stockée par identifiant.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement se résolvant en ligne d'enregistrement vectoriel gérée, telle que "message", "memory", "guideline", "fact" ou "preference".
  • 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" ou "preference").
  • limit int – Nombre maximum d'enregistrements à renvoyer.
  • 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 non ciblés sur la dimension de thread sont renvoyés.
  • 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 la portée n'est pas définie sur la dimension utilisateur sont renvoyés.
  • 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 non ciblés sur la dimension d'agent sont renvoyés.
  • 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]

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']

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 à inclure. Lorsqu'elle est omise, la recherche couvre tout type d'enregistrement.
  • 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 ou preference)
  • record_id str : identificateur du message ou de la ligne de mémoire à 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.