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 `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, les souvenirs et les profils d'acteur.

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_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. Ce texte est stocké en tant que contenu du profil et utilisé pour créer la rangée d'intégration du profil dans RECORD_CHUNKS.
Retours : Identificateur de l'enregistrement de profil d'agent inséré.
Type de retour : str

Notes

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 d'utilisateur.

Paramètres :
- user_id str – Identificateur d'utilisateur.
- informations str – Informations à structure libre sur l'utilisateur. Ce texte est stocké en tant que contenu du profil et utilisé pour créer la rangée d'intégration du profil dans RECORD_CHUNKS.
Retours : Identificateur de l'enregistrement de profil d'utilisateur inséré.
Type de retour : str

Notes

La portée des enregistrements de profil d'utilisateur n'est pas définie. 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`

Sert à supprimer un enregistrement géré et ses enregistrements de fragmentation par code.

Paramètres :
- record_type str – Étiquette 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, vers leurs rangées enfants avec portée dans la même transaction. Pour une cible de profil d'utilisateur ou de profil d'agent, cela supprime d'abord les rangées d'unité d'exécution détenues, ce qui supprime leur message d'unité d'exécution et leurs rangées de table de mémoire, puis supprime tous les messages d'acteur direct restants et les rangées de type mémoire (memory, guideline, fact, preference). Ce nettoyage de portée est toujours exécuté lorsque l'enregistrement de profil correspondant est déjà absent.
Retours : Nombre de cibles de niveau supérieur demandées supprimées, généralement 0 ou 1. Les rangées enfants en cascade ne sont pas comptées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage de portée.
Type de retour : int

Notes

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 du profil et toutes les suppressions enfants ciblées sont validées ou repositionné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`

Supprimez un thread et les lignes stockées associées.

Paramètres : thread_id str – Identificateur de fil dont les rangées doivent être supprimées, notamment la rangée d'unité d'exécution, les rangées enfants dépendantes et le nettoyage explicite des rangées de tranche de mémoire.
Retours : Nombre de rangées d'unité d'exécution supprimées (0 ou 1).
Type de retour : int

Notes

Utilisez cette opération lorsque vous avez besoin d'un nettoyage en cascade avec une portée de fil. Dans l'espace de stockage soutenu par la base de données, la suppression de l'unité d'exécution supprime la ligne d'unité d'exécution gérée ainsi que les lignes de message et de mémoire associées, plus les lignes de fragment de table mises à jour pour l'extraction. Ceci est plus large qu'une suppression au niveau du message, qui supprime uniquement l'enregistrement de message brut. La suppression d'unité d'exécution supprime les rangées dépendantes de message et de mémoire référencées dans THREAD ainsi que les rangées RECORD_CHUNKS correspondantes dans la même transaction.

Exemples

store.delete_thread("c1")
0

méthode `get`

Extraire un enregistrement stocké par identificateur.

Paramètres :
- record_type str – Étiquette de type d'enregistrement résolue en une rangée gérée, telle que "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile".
- 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", "preference", "user_profile" ou "agent_profile").
- limite int | None – Nombre maximal facultatif d'enregistrements à retourner. Lorsqu'il est omis, le magasin utilise son plafond de liste par défaut. Transmettez None pour désactiver ce plafond et retourner chaque enregistrement correspondant.
- 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, seules les rangées dont thread_id est SQL NULL sont retournées. Les types d'enregistrement sans portée ignorent ce filtre.
- 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, seules les rangées dont user_id est SQL NULL sont retournées. Les types d'enregistrement sans portée ignorent ce filtre.
- 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, seules les rangées dont agent_id est SQL NULL sont retournées. Les types d'enregistrement sans portée ignorent ce filtre.
- 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]

Notes

"user_profile" et "agent_profile" sont des types d'enregistrement sans portée. 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 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 interrogeables à inclure. Lorsqu'elle est omise, la recherche de base de données couvre les messages, les lignes de table mémoire et les profils d'acteur. Les profils d'acteur contribuent à leurs données utiles information, tandis que les rangées de message et de mémoire contribuent à leurs données utiles content. Lors de la recherche, les types d'enregistrement de profil utilisent leur identificateur d'acteur pour la dimension d'étendue applicable tandis que les autres dimensions d'étendue se comportent comme None.
- 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", "preference", "user_profile" ou "agent_profile")
- record_id str – Identificateur de la rangée 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 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.

Magasins et schéma

API de magasin

classe oracleagentmemory.core.OracleMemoryStore

méthode search (résumé)

Magasin Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

méthode add_agent

méthode add_user

méthode delete

méthode delete_thread

méthode get

méthode list

méthode list_thread_messages

méthode search

méthode update

Politique de schéma

classe oracleagentmemory.core.SchemaPolicy

EXIGENCES EXISTANTES

CREATE_IF_VIDE

CRÉER SI NÉCESSAIRE

RECRÉEZ

classe `oracleagentmemory.core.OracleMemoryStore`

méthode `search` (résumé)

classe `oracleagentmemory.core.OracleDBMemoryStore`

méthode `add_agent`

méthode `add_user`

méthode `delete`

méthode `delete_thread`

méthode `get`

méthode `list`

méthode `list_thread_messages`

méthode `search`

méthode `update`

classe `oracleagentmemory.core.SchemaPolicy`