Magasins et schéma

Cette page présente les abstractions du magasin principal et les contrôles de schéma utilisés par la trousse SDK de mémoire de l'agent Oracle.

API de magasin

classe oracleagentmemory.core.OracleMemoryStore

Bases : IMemoryStore

Interface de magasin commune utilisée par OracleAgentMemory.

Une implémentation de magasin est responsable de la persistance des enregistrements de texte et de la recherche de similarité. Les points d'entrée synchrones et asynchrones sont définis afin que les API de niveau supérieur puissent exposer les surfaces de synchronisation/asynchrones correspondantes sans dupliquer la logique propre au magasin.

méthode add (résumé)

Intégrer et conserver des enregistrements de texte.

• Paramètres :
  • contenu list[str | None] – Données utiles de texte à stocker. Ces valeurs sont également utilisées comme données utiles d'intégration lorsque index_texts n'est pas fourni. Lorsqu'un élément est omis (None), les magasins le résolvent à partir de la clé de métadonnées "content" lorsqu'il est disponible; sinon, le contenu vide est conservé.
  • record_type str – Étiquette de type d'enregistrement pour les enregistrements stockés (par exemple "message" ou "memory").
  • index_texts list[str] – Données utiles d'intégration facultatives uniquement alignées sur contents.
  • embeddings list[list[float]] | list[ndarray] – Vecteurs d'intégration précalculés facultatifs alignés avec 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 enregistrements facultatifs visibles par l'appelant. Doit être entièrement fourni (un par texte) ou omis pour tous les textes. Les ID retourné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 facultatifs de portée stockés avec les enregistrements.
  • agent_ids str | None | list[str | None] – Identificateurs facultatifs d'étendue stockés avec les enregistrements.
  • roles str | None | list[str | None] – Rôle de clavardage facultatif pour les enregistrements de message.
  • horodatages str | None | list[str | None] – Horodatage facultatif ou horodatage par enregistrement.
  • métadonnées dict[str, Any] | list[dict[str, Any] | None] | None – Mappage de métadonnées facultatif ou mappages 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 (Any) – Options d'écriture propres au magasin transmises par des API de niveau supérieur.
• Retours : Insérez des identificateurs pour chaque élément de contenu d'entrée. Ceux-ci correspondent à record_ids lorsqu'ils sont fournis; sinon, ils stockent les identificateurs générés.
• Type de retour : list[str]

Exemples

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

méthode search (résumé)

recherche d'enregistrements par similarité;

• Paramètres :
  • query str | None – Interrogation en langage naturel. Doit être fourni lorsque query_vector est omis.
  • query_vector list[float] | None – Intégration facultative des interrogations précalculées. Vous devez fournir exactement l'une des valeurs query et query_vector.
  • k int – Nombre maximal de résultats à retourner. Les valeurs explicites doivent être au moins 1.
  • thread_id str | None – Portée d'unité d'exécution facultative.
  • user_id str | None – Filtres facultatifs d'étendue d'utilisateur et d'agent.
  • agent_id str | None – Filtres facultatifs d'étendue d'utilisateur et d'agent.
  • exact_user_match bool – Indique si chaque identificateur de portée fourni doit être mis en correspondance exactement.
  • exact_agent_match bool – Indique si chaque identificateur de portée fourni doit être mis en correspondance exactement.
  • exact_thread_match bool – Indique si chaque identificateur de portée fourni doit être mis en correspondance exactement.
  • record_types set[str] | None – Jeu facultatif de types d'enregistrement à inclure.
  • metadata_filter dict[str, Any] | None – Mappage partiel de métadonnées facultatif. Un enregistrement ne correspond que 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-ensembles récursifs. Par conséquent, l'ordre et la longueur de la liste doivent également correspondre.
• Retours : Paires (record, distance) triées en fonction de la distance croissante.
• Type de retour : list[tuple[Enregistrement, float]]
• Élargissements : 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'

Filtre 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

Correspondance exacte d'une valeur de liste, ordre compris :

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

Magasin Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases : OracleMemoryStore

Persistance soutenue par la base de données pour les messages et les enregistrements de mémoire typés.

Créez un magasin Oracle DB.

• Paramètres :
  • embedder IEmbedder | None – Embedder utilisé pour les types d'enregistrement vectorisé. Peut être None lorsque les appelants fournissent toujours des vecteurs précalculés dans add, update et search.
  • pool Any – Connexion ou réserve Oracle DB. La transmission d'une connexion brute active le mode monosession pour cette instance de magasin : les appels de magasin simultanés sont sérialisés localement pour préserver les hypothèses de verrouillage de ligne et de transaction utilisées par les opérations d'écriture. Utilisez une réserve de connexions pour les demandes concurrentes.
  • schema_policy SchemaPolicy | str – Mode de configuration du schéma. Par défaut, un schéma géré existant et à jour est requis et aucune modification LDD n'est effectuée. 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 – Intégration de la dimension pour la création de schéma lors de la création des colonnes VECTOR.
  • table_name_prefix str – Préfixe facultatif ajouté aux noms de table/d'index gérés.

méthode add

Ajoutez des enregistrements à la mémoire.

• Paramètres :
  • contenu list[str | None] – Données utiles de 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), les magasins le résolvent à partir de la clé de métadonnées "content" lorsqu'il est disponible; sinon, le contenu vide est conservé.
  • record_type str – Étiquette de type d'enregistrement pour les enregistrements stockés (par exemple "message", "memory", guideline, fact ou preference).
  • index_texts list[str] – Données utiles alternatives facultatives utilisées uniquement pour l'intégration/l'indexation. Lorsque cette option 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 avec 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 n'utilise l'intégrateur que pour les données utiles d'indexation non vides; les chaînes vides explicites sont stockées sans intégration de bloc.
  • record_ids str | None | list[str] | list[None] – ID enregistrements facultatifs visibles par l'appelant. Doit être entièrement fourni (un par texte) ou omis pour tous les textes. Les ID retourné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 facultatifs de portée stockés avec les enregistrements.
  • agent_ids str | None | list[str | None] – Identificateurs facultatifs d'étendue stockés avec les enregistrements.
  • roles str | None | list[str | None] – Rôle de clavardage facultatif pour les enregistrements de message.
  • horodatages str | None | list[str | None] – Horodatages d'événement facultatifs fournis par l'appelant.
  • métadonnées 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 la création de lots Oracle executemany.
• Retours : Insérez des identificateurs pour chaque élément de contenu d'entrée. Ces valeurs correspondent à record_ids lorsqu'elles sont fournies; sinon, elles stockent les ID générés par 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

ajout d'une table de profil d'agent;

• Paramètres :
  • agent_id str – Identificateur de l'agent.
  • informations str – Informations à structure 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 d'utilisateur.

• Paramètres :
  • user_id str – Identificateur d'utilisateur.
  • informations str – Informations à structure libre sur l'utilisateur.
• Retours : Identificateur de l'enregistrement de profil d'utilisateur inséré.
• Type de retour : str

Exemples

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

méthode delete

Supprimez un enregistrement de table vectorielle gérée et ses enregistrements de fragmentation par identificateur.

• Paramètres :
  • record_type str – Étiquette de type d'enregistrement dont la table gérée doit être ciblée, par exemple "message", "memory", "guideline", "fact" ou "preference"
  • record_id str – Identificateur de la rangée à supprimer.
• Retours : Nombre de rangées supprimé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

Supprimez un fil et les enregistrements de table vectorielle et de fragmentation associés.

• Paramètres : thread_id str – Identificateur de fil dont les rangées doivent être supprimées (y compris les rangées enfants supprimées en cascade).
• Retours : Nombre de rangées d'unité d'exécution supprimées (0 ou 1).
• Type de retour : int

Exemples

store.delete_thread("c1")
0

méthode get

Extraire un message ou une mémoire stockée par identificateur.

• Paramètres :
  • record_type str – Étiquette de type d'enregistrement résolue en une rangée d'enregistrement vectoriel gérée, par exemple "message", "memory", "guideline", "fact" ou "preference".
  • record_id str – Identificateur à rechercher.
• Retours : Enregistrement alimenté 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

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

• Paramètres :
  • record_type str – Étiquette de type d'enregistrement (par exemple, "message", "memory", "guideline", "fact" ou "preference").
  • limite int – Nombre maximum d'enregistrements à retourner.
  • thread_id str | None – Filtre de portée d'unité d'exécution exact. Lorsqu'elle est omise, aucun filtrage n'est appliqué. Lorsque cette option est réglée à None, seuls les enregistrements sans portée sur la dimension d'unité d'exécution sont retournés.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'elle est omise, aucun filtrage n'est appliqué. Lorsque cette option est réglée à None, seuls les enregistrements sans portée sur la dimension Utilisateur sont retournés.
  • agent_id str | None – Filtre de portée d'agent exact. Lorsqu'elle est omise, aucun filtrage n'est appliqué. Lorsque cette option est réglée à None, seuls les enregistrements sans portée sur la dimension Agent sont retournés.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'elle est omise, aucun filtrage n'est appliqué. Lorsque cette option est réglée à None, seuls les enregistrements sans métadonnées stockées sont retournés. Lorsque cette option est définie sur une dictée, 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-ensembles récursifs. 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 fil dont les messages doivent être retournés.
  • last_n int | None – Nombre facultatif de messages les plus récents à retourner.
• Retours : Enregistrements de message triés par ordre d'insertion.
• Type de retour : list[MessageRecord]

Exemples

store.list_thread_messages("c1")
[]

méthode search

recherche d'enregistrements par similarité;

• Paramètres :
  • query str | None – Interrogation en langage naturel. Doit être fourni lorsque query_vector est omis.
  • query_vector list[float] | None – Intégration facultative des interrogations précalculées. Vous devez fournir exactement l'une des valeurs query et query_vector.
  • k int – Nombre maximal de résultats à retourner. Les valeurs explicites doivent être au moins 1.
  • thread_id str | None – Identificateur de portée d'unité d'exécution facultatif. exact_thread_match=False laisse la dimension d'unité d'exécution sans contrainte. exact_thread_match=True correspond exactement à la valeur thread_id fournie. Si thread_id=None, il ne correspond qu'aux enregistrements sans portée sur la dimension d'unité d'exécution.
  • user_id str | None – Identificateurs facultatifs d'étendue d'utilisateur et d'agent. 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 ne correspond qu'aux enregistrements sans portée sur cette dimension.
  • agent_id str | None – Identificateurs facultatifs d'étendue d'utilisateur et d'agent. 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 ne correspond qu'aux enregistrements sans portée sur cette dimension.
  • exact_user_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 sans portée 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 sans portée 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 sans portée de cette dimension.
  • record_types set[str] | None – Jeu facultatif de types d'enregistrement à inclure. Lorsqu'elle est omise, la recherche couvre n'importe quel type d'enregistrement.
  • metadata_filter dict[str, Any] | None – Mappage partiel de métadonnées facultatif. Un enregistrement ne correspond que 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-ensembles récursifs. Par conséquent, l'ordre et la longueur de la liste doivent également correspondre.
• Retours : Paires (record, distance) triées en fonction de la distance croissante.
• Type de retour : list[tuple[Enregistrement, float]]
• Élargissements : 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'

Filtre 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

Correspondance exacte d'une valeur de liste, ordre compris :

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

mise à jour du contenu de la table stockée, de l'intégration des fragments et des valeurs des métadonnées;

• Paramètres :
  • record_type str – Étiquette de type d'enregistrement de la rangée en cours de modification (par exemple "message", "memory", guideline, fact ou preference)
  • record_id str – Identificateur du message ou de la rangée 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 des arguments sémantiques omis dans le même appel. Transmettez "" pour conserver le contenu vide explicite lors de l'effacement de toute intégration de bloc pour cet enregistrement. Lorsqu'il est omis, le contenu existant reste inchangé.
  • index_text str | None – Données utiles d'intégration facultatives uniquement. Lorsqu'elle est omise, text est intégré.
  • intégration 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.
  • métadonnées dict[str, Any] | None – Mappage de métadonnées facultatif sérialisé vers JSON et stocké dans metadata.
• Retours : Nombre de rangées mises à jour (0 ou 1). Retourne 0 lorsqu'aucun enregistrement logique ne correspond à record_type et record_id.
• Type de retour : int
• Lances : ValueError – Si record_type n'est pas pris en charge, si aucune donnée 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'

Politique de schéma

classe oracleagentmemory.core.SchemaPolicy

Bases : str, Enum

Politique de création de schéma pour les magasins Oracle DB.

EXIGENCES EXISTANTES

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

CREATE_IF_VIDE

S'il n'existe aucun objet géré, amorcer 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éer uniquement les objets gérés manquants, y compris les métadonnées.

RECRÉEZ

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