Negozi e schema

Questa pagina presenta le astrazioni dell'area di memorizzazione principale e i controlli dello schema utilizzati dall'SDK di memoria dell'agente Oracle.

API negozio

classe oracleagentmemory.core.OracleMemoryStore

Basi: IMemoryStore

Interfaccia di memorizzazione comune utilizzata da OracleAgentMemory.

Un'implementazione del negozio è responsabile della persistenza dei record di testo e dell'esecuzione di ricerche di somiglianza su di essi. Entrambi i punti di accesso sincrono e asincrono sono definiti in modo che le API di livello superiore possano esporre le superfici di sincronizzazione/asincroni corrispondenti senza duplicare la logica specifica dell'area di memorizzazione.

metodo add

Aggiungere record al negozio.

• Parametri:
  • contents list[str | None]: registra i payload per renderli persistenti. I valori di testo vengono utilizzati anche per l'incorporamento, a meno che non vengano forniti index_texts o embeddings. Quando il valore di testo è None, le implementazioni possono tornare a metadata["content"]. Le stringhe vuote esplicite vengono conservate.
  • record_type str: tipo di record logico da creare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • index_texts list[str]: payload alternativi facoltativi utilizzati solo per l'incorporamento o l'indicizzazione. Se specificato, deve allinearsi agli input di testo.
  • embeddings list[list[float]] | list[ndarray]: vettori di incorporamento precalcolati facoltativi allineati con gli input di testo. Se fornito, il negozio deve utilizzare questi vettori direttamente invece di invocare il suo embedder. Se non fornito, il negozio deve avere un embedder collegato, altrimenti verrà sollevato un errore.
  • record_ids str | None | list[str | None]: identificativi facoltativi visibili al chiamante. È possibile utilizzare una singola stringa per gli inserimenti di un record, mentre gli elenchi devono essere allineati agli input di testo. Gli identificativi generati vengono restituiti quando questo campo viene omesso.
  • thread_ids str | None | list[str | None]: identificativi di thread facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • user_ids str | None | list[str | None]: identificativi utente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • agent_ids str | None | list[str | None]: identificativi agente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • roles str | None | list[str | None]: ruoli messaggio facoltativi quali "user" o "assistant". I valori scalari possono essere trasmessi attraverso input di testo allineati. Utilizzato solo se record_type è "message".
  • timestamp str | None | list[str | None]: indicatori orari degli eventi facoltativi per rendere persistenti i record. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None: dizionari di metadati forniti dal chiamante opzionali. I metadati possono includere "content" come origine di fallback quando un valore di testo viene omesso anziché impostato in modo esplicito su "".
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Tipo restituito: list[str]

Note

Utilizzare add_batches() quando il chiamante dispone già di uno o più oggetti PendingRecordBatch.

• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dell'input.
• Tipo restituito: elenco[str]
• Parametri:
  • contenuti list[str | None]
  • tipo_record str
  • testi_indice list[str]
  • embeding list[list[float]] | list[ndarray]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

metodo add_agent (abstract)

Aggiungere un record profilo agente.

• Parametri:
  • agent_id str: identificativo stabile per il profilo dell'agente.
  • information str: testo in formato libero che descrive l'agente.
• Restituzioni: identificativo del record profilo agente creato.
• Tipo restituito: str

metodo add_async (asincrono)

Aggiungere in modo asincrono record orientati alle righe al negozio.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add().

• Parametri:
  • contenuti list[str | None]
  • tipo_record str
  • testi_indice list[str]
  • embeding list[list[float]] | list[ndarray]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_batches

Aggiungere batch logici preparati dal chiamante all'area di memorizzazione.

• Parametri:
  • batches list[PendingRecordBatch]: batch logici completamente preparati da rendere persistenti. Ogni batch deve contenere i propri campi per record, ad esempio record_type, valori di ambito, ruoli, indicatori orari e metadati.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dei batch e delle righe di input.
• Tipo restituito: elenco[str]

Esempi

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

metodo add_batches_async (asincrono)

Aggiungere in modo asincrono batch logici preparati dal chiamante all'area di memorizzazione.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add_batches().

• Parametri:
  • batch list[PendingRecordBatch]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_user (abstract)

Aggiungere un record profilo utente.

• Parametri:
  • user_id str: identificativo stabile per il profilo utente.
  • information str: testo in formato libero che descrive l'utente.
• Restituzioni: identificativo del record profilo utente creato.
• Tipo restituito: str

metodo delete (abstract)

Eliminare un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: tipo logico del record da rimuovere.
  • record_id str: identificativo del record da rimuovere.
  • cascade bool: quando si utilizza True, applicare qualsiasi comportamento di eliminazione a catena supportato dall'area di memorizzazione per le destinazioni di livello superiore richieste all'interno della stessa operazione di eliminazione. Viene utilizzato principalmente per destinazioni quali i profili attore che possiedono record con ambito aggiuntivo. Ad esempio, una cascata di profilo utente o di profilo agente può eliminare i thread di proprietà stessi, i messaggi con ambito thread e i record di memoria rimossi con tali thread e qualsiasi record con ambito attore diretto rimanente come messaggi, memorie, linee guida, fatti o preferenze. Per l'eliminazione del profilo attore, questo cleanup con ambito può essere ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di record di livello superiore richiesti eliminati, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

metodo delete_thread (abstract)

Eliminare un thread e i dati memorizzati associati.

• Parametri: thread_id str: identificativo del thread da rimuovere.
• Restituzioni: numero di record thread eliminati, in genere 0 o 1.
• Tipo restituito: int.

Note

Operazione a livello di negozio per la rimozione di un thread e dei record con ambito thread gestiti dal negozio. Preferire l'eliminazione dei thread quando i requisiti di conservazione richiedono l'eliminazione sia dei messaggi di origine che dei dati di memoria con ambito thread derivato, poiché le eliminazioni a livello di messaggio non implicano la rimozione di record derivati con persistenza separata.

metodo get (abstract)

Recupera un record memorizzato per tipo e identificativo.

• Parametri:
  • record_type str: tipo logico del record da recuperare.
  • record_id str: identificativo del record da recuperare.
• Restituisce: il record memorizzato, se trovato, altrimenti None.
• Tipo restituito: Record | Nessuno

metodo list (abstract)

Elenca i record memorizzati per un tipo di record.

• Parametri:
  • record_type str: tipo di record logico da enumerare.
  • limite int | None: numero massimo facoltativo di record più recenti da restituire. Se omesso, le implementazioni possono applicare un limite superiore sicuro come MAX_LIST_LIMIT. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui thread_id è None. I tipi di record senza ambito ignorano questo filtro.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui user_id è None. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record il cui agent_id è None. I tipi di record senza ambito ignorano questo filtro.
• Restituzioni: record ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: elenco[Record]

metodo list_thread_messages (abstract)

Elenca la cronologia dei messaggi memorizzata per una discussione.

• Parametri:
  • thread_id str: identificativo del thread in cui devono essere restituiti i messaggi.
  • last_n int | None: numero facoltativo di messaggi più recenti da includere. Se omesso, vengono restituiti tutti i messaggi memorizzati per il thread.
• Restituzioni: i record dei messaggi ordinati dal meno recente al più recente all'interno della finestra restituita.
• Tipo restituito: List[MessageRecord]

metodo search (abstract)

Cerca i record per somiglianza.

• Parametri:
  • query str | None: query in linguaggio naturale. Deve essere fornito quando query_vector viene omesso.
  • query_vector list[float] | None: incorporamento facoltativo di query precalcolate. Specificare esattamente uno dei valori query e query_vector.
  • k int: numero massimo di risultati da restituire. I valori espliciti devono essere almeno 1.
  • thread_id str | None: ambito del thread facoltativo.
  • user_id str | None: filtri facoltativi per l'ambito di utente e agente.
  • agent_id str | None: filtri facoltativi per l'ambito dell'utente e dell'agente.
  • exact_user_match bool: indica se ogni identificativo di ambito specificato deve avere una corrispondenza esatta.
  • exact_agent_match bool: indica se ogni identificativo di ambito fornito deve avere una corrispondenza esatta.
  • exact_thread_match bool: indica se ogni identificativo di ambito fornito deve avere una corrispondenza esatta.
  • record_types set[str] | None: set facoltativo di tipi di record da includere.
  • metadata_filter dict[str, Any] | None: mapping facoltativo di metadati parziali. Un record corrisponde solo quando i relativi metadati memorizzati contengono tutte le chiavi e i valori richiesti. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori di elenco vengono abbinati in base all'uguaglianza esatta anziché alla corrispondenza ricorsiva del subset, pertanto l'ordine e la lunghezza dell'elenco devono corrispondere.
• Restituzioni: coppie (record, distance) ordinate in base alla distanza crescente.
• Tipo restituito: list[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

Esempi

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'

Filtra in base a un valore di metadati scalare:

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

Filtra in base ai metadati nidificati:

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

Corrisponde esattamente a un valore di elenco, incluso l'ordine:

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

metodo search_async (asincrono)

Cerca i record in modo asincrono in base alla somiglianza vettoriale.

• Parametri:
  • query str | None: lo stesso testo di query accettato da search.
  • k int: conteggio massimo dei risultati accettato da search. I valori espliciti devono essere almeno 1.
  • query_vector list[float] | None: incorporamento facoltativo della stessa query precalcolata accettato da search.
  • thread_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • user_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • agent_id str | None: filtri di ambito opzionali uguali accettati da search.
  • exact_user_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_agent_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_thread_match bool: flag della stessa corrispondenza esatta accettati da search.
  • record_types set[str] | None: filtro del tipo di record opzionale accettato da search.
• Restituzioni: coppie (record, distance) restituite dalla chiamata search sottostante.
• Tipo restituito: List[tuple[Record, float]]
• Aumenti: ValueError: se k è minore di 1.

metodo update (abstract)

Aggiorna il contenuto dei record memorizzati, incorporando dati o metadati.

• Parametri:
  • record_type str: tipo logico di record da aggiornare.
  • record_id str: identificativo del record da aggiornare.
  • testo str | None: contenuto sostitutivo opzionale. Passare None per cancellare in modo esplicito il testo memorizzato quando è supportato dall'area di memorizzazione. I negozi possono anche cancellare lo stato semantico associato e rifiutare gli aggiornamenti index_text o embedding non nulli in conflitto nella stessa chiamata. Omettere l'argomento per non modificare il contenuto.
  • index_text str | None: payload facoltativo di sola incorporazione utilizzato per ricalcolare il vettore memorizzato senza modificare il testo persistente.
  • incorporamento list[float] | ndarray | None: vettore di incorporamento precomputato facoltativo. Se fornito, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Passare None per cancellare in modo esplicito l'incorporamento memorizzato quando l'area di memorizzazione lo supporta.
  • metadata dict[str, Any] | None: mapping dei metadati di sostituzione facoltativo. Passare None per cancellare i metadati quando l'area di memorizzazione li supporta.
• Restituzioni: numero di record aggiornati, in genere 0 o 1. Restituisce 0 quando nessun record memorizzato corrisponde all'identificativo logico richiesto.
• Tipo restituito: int.
• Aumenti: ValueError: se il payload di aggiornamento non è valido per l'area di memorizzazione, ad esempio omettendo ogni campo facoltativo o fornendo argomenti semantici in conflitto.

Area di memorizzazione Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Basi: OracleMemoryStore

Persistenza supportata dal database per messaggi, memorie e profili degli attori.

Creare un'area di memorizzazione Oracle DB.

• Parametri:
  • embedder IEmbedder | None: incorporamento utilizzato per i tipi di record vettorializzati. Può essere None quando i chiamanti forniscono sempre vettori precalcolati in add, update e search.
  • pool Any: connessione o pool Oracle DB. Il passaggio di una connessione raw abilita la modalità a sessione singola per questa istanza dell'area di memorizzazione: le chiamate dell'area di memorizzazione concorrente vengono serializzate localmente per conservare le ipotesi di blocco delle righe e delle transazioni utilizzate dalle operazioni di scrittura. Utilizzare un connection pool per le richieste concorrenti.
  • schema_policy SchemaPolicy | str: modalità di impostazione dello schema. L'impostazione predefinita richiede uno schema gestito esistente e aggiornato e non esegue alcuna modifica DDL. Utilizzare SchemaPolicy.CREATE_IF_NECESSARY per riempire gli oggetti mancanti oppure SchemaPolicy.RECREATE per eliminare e ricreare gli oggetti gestiti.
  • vector_dim int: incorporamento della dimensione per la creazione dello schema quando vengono create colonne VECTOR.
  • table_name_prefix str: prefisso facoltativo aggiunto ai nomi di tabella/indice gestiti.

metodo add

Aggiungere record al negozio.

• Parametri:
  • contents list[str | None]: registra i payload per renderli persistenti. I valori di testo vengono utilizzati anche per l'incorporamento, a meno che non vengano forniti index_texts o embeddings. Quando il valore di testo è None, le implementazioni possono tornare a metadata["content"]. Le stringhe vuote esplicite vengono conservate.
  • record_type str: tipo di record logico da creare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • index_texts list[str]: payload alternativi facoltativi utilizzati solo per l'incorporamento o l'indicizzazione. Se specificato, deve allinearsi agli input di testo.
  • embeddings list[list[float]] | list[ndarray]: vettori di incorporamento precalcolati facoltativi allineati con gli input di testo. Se fornito, il negozio deve utilizzare questi vettori direttamente invece di invocare il suo embedder. Se non fornito, il negozio deve avere un embedder collegato, altrimenti verrà sollevato un errore.
  • record_ids str | None | list[str | None]: identificativi facoltativi visibili al chiamante. È possibile utilizzare una singola stringa per gli inserimenti di un record, mentre gli elenchi devono essere allineati agli input di testo. Gli identificativi generati vengono restituiti quando questo campo viene omesso.
  • thread_ids str | None | list[str | None]: identificativi di thread facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • user_ids str | None | list[str | None]: identificativi utente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • agent_ids str | None | list[str | None]: identificativi agente facoltativi associati ai record inseriti. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • roles str | None | list[str | None]: ruoli messaggio facoltativi quali "user" o "assistant". I valori scalari possono essere trasmessi attraverso input di testo allineati. Utilizzato solo se record_type è "message".
  • timestamp str | None | list[str | None]: indicatori orari degli eventi facoltativi per rendere persistenti i record. I valori scalari possono essere trasmessi attraverso input di testo allineati.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None: dizionari di metadati forniti dal chiamante opzionali. I metadati possono includere "content" come origine di fallback quando un valore di testo viene omesso anziché impostato in modo esplicito su "".
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Tipo restituito: list[str]

Note

Utilizzare add_batches() quando il chiamante dispone già di uno o più oggetti PendingRecordBatch.

• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dell'input.
• Tipo restituito: elenco[str]
• Parametri:
  • contenuti list[str | None]
  • tipo_record str
  • testi_indice list[str]
  • embeding list[list[float]] | list[ndarray]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

metodo add_async (asincrono)

Aggiungere in modo asincrono record orientati alle righe al negozio.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add().

• Parametri:
  • contenuti list[str | None]
  • tipo_record str
  • testi_indice list[str]
  • embeding list[list[float]] | list[ndarray]
  • ID_record str | None | list[str | None]
  • id_thread str | None | list[str | None]
  • ID_utente str | None | list[str | None]
  • id_agente str | None | list[str | None]
  • ruoli str | None | list[str | None]
  • Indicatori data/ora str | None | list[str | None]
  • metadati dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_batches

Aggiungere batch logici preparati dal chiamante all'area di memorizzazione.

• Parametri:
  • batches list[PendingRecordBatch]: batch logici completamente preparati da rendere persistenti. Ogni batch deve contenere i propri campi per record, ad esempio record_type, valori di ambito, ruoli, indicatori orari e metadati.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'implementazione inoltrate al negozio concreto.
• Restituzioni: identificativi per i record inseriti, nello stesso ordine logico dei batch e delle righe di input.
• Tipo restituito: elenco[str]

Esempi

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

metodo add_batches_async (asincrono)

Aggiungere in modo asincrono batch logici preparati dal chiamante all'area di memorizzazione.

Accetta gli stessi argomenti e restituisce gli stessi identificativi di add_batches().

• Parametri:
  • batch list[PendingRecordBatch]
  • store_kwargs Any
• Tipo restituito: list[str]

metodo add_agent

Aggiungere un record profilo agente.

• Parametri:
  • agent_id str: identificativo dell'agente.
  • informazioni str: informazioni in formato libero sull'agente. Questo testo viene memorizzato come contenuto del profilo e utilizzato per creare la riga di incorporamento del profilo in RECORD_CHUNKS.
• Restituzioni: identificativo del record profilo agente inserito.
• Tipo restituito: str

Note

I record profilo agente non hanno ambito. L'identificativo di record pubblico inserito è lo stesso valore passato come agent_id.

Esempi

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

metodo add_user

Aggiungere un record profilo utente.

• Parametri:
  • user_id str: identificativo utente.
  • informazioni str: informazioni in formato libero sull'utente. Questo testo viene memorizzato come contenuto del profilo e utilizzato per creare la riga di incorporamento del profilo in RECORD_CHUNKS.
• Restituzioni: identificativo del record del profilo utente inserito.
• Tipo restituito: str

Note

I record profilo utente non hanno ambito. L'identificativo di record pubblico inserito è lo stesso valore passato come user_id.

Esempi

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

metodo delete

Eliminare una riga gestita e le relative righe chunk in base all'identificativo.

• Parametri:
  • record_type str: etichetta del tipo di record da eliminare. I tipi supportati includono "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" e "agent_profile".
  • record_id str: identificativo da eliminare.
  • a cascata bool: quando si utilizza True, espandere le destinazioni di livello superiore supportate, ad esempio i profili attore, nelle righe figlio con ambito all'interno della stessa transazione. Per una destinazione di profilo utente o di profilo agente, vengono eliminate prima le righe di thread di proprietà, che rimuovono i messaggi con ambito thread e le righe della tabella di memoria, quindi i messaggi con ambito attore e le righe simili alla memoria rimanenti (memory, guideline, fact, preference). Il cleanup con ambito viene ancora eseguito quando la riga del profilo corrispondente è già assente.
• Restituzioni: numero di destinazioni di livello superiore richieste rimosse, in genere 0 o 1. Le righe figlio a catena non vengono conteggiate separatamente, pertanto è possibile che sia ancora 0 quando un profilo attore mancante attiva il cleanup con ambito.
• Tipo restituito: int.

Note

L'operazione viene eseguita all'interno di una transazione. Quando cascade è abilitato per una destinazione di livello superiore supportata, l'eliminazione del profilo e tutte le eliminazioni figlio con ambito vengono sottoposte a commit o sottoposte a rollback insieme.

Esempi

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

metodo delete_thread

Eliminare un thread e le relative righe memorizzate associate.

• Parametri: thread_id str: identificativo del thread le cui righe devono essere rimosse, incluse la riga del thread, le righe figlio dipendenti e il cleanup esplicito della riga chunk.
• Restituzioni: numero di righe di thread eliminate (0 o 1).
• Tipo restituito: int.

Note

Utilizzare questa operazione quando è necessario eseguire il cleanup a cascata con ambito thread. Nell'area di memorizzazione supportata dal database, l'eliminazione del thread comporta la rimozione della riga del thread gestito insieme alle righe di messaggio e memoria associate, oltre alle righe del blocco di record gestite per il recupero. Questa operazione è più ampia di un'eliminazione a livello di messaggio, che rimuove solo la riga del messaggio raw. L'eliminazione del thread rimuove le righe di messaggio e memoria dipendenti a cui viene fatto riferimento da THREAD insieme alle righe RECORD_CHUNKS corrispondenti nella stessa transazione.

Esempi

store.delete_thread("c1")
0

metodo get

Recupera un record memorizzato in base all'identificativo.

• Parametri:
  • record_type str: etichetta del tipo di record che viene risolta in una riga gestita, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • record_id str: identificativo di cui eseguire la ricerca.
• Restituzioni: record popolato con metadati decodificati se trovati, altrimenti None.
• Tipo restituito: Record | Nessuno

Esempi

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'

metodo list

Enumerare i record persistenti per un tipo di record.

• Parametri:
  • record_type str: etichetta del tipo di record (ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile").
  • limite int | None: numero massimo facoltativo di record da restituire. Se omesso, il negozio utilizza il suo limite predefinito. Passare None per disabilitare il limite e restituire ogni record corrispondente.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui thread_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro.
  • user_id str | None: filtro esatto dell'ambito utente. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui user_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituite solo le righe il cui agent_id è SQL NULL. I tipi di record senza ambito ignorano questo filtro.
  • metadata_filter dict[str, Any] | None: filtro dei metadati. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record senza metadati memorizzati. Se impostato su un parametro, i metadati memorizzati devono contenere tutte le chiavi e tutti i valori richiesti. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori di elenco vengono abbinati in base all'uguaglianza esatta anziché alla corrispondenza ricorsiva del subset, pertanto l'ordine e la lunghezza dell'elenco devono corrispondere.
• Restituzioni: record ordinati in base all'ordine di inserimento.
• Tipo restituito: list[Record]

Note

"user_profile" e "agent_profile" sono tipi di record senza ambito. Per questi tipi di record, thread_id, user_id e agent_id vengono ignorati e l'identità dell'attore rimane in record.id.

Esempi

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

metodo list_thread_messages

Restituisci messaggi persistenti per un thread.

• Parametri:
  • thread_id str: identificativo del thread i cui messaggi devono essere restituiti.
  • last_n int | None: numero facoltativo di messaggi più recenti da restituire.
• Restituzioni: record di messaggi ordinati in base all'ordine di inserimento.
• Tipo restituito: list[MessageRecord]

Esempi

store.list_thread_messages("c1")
[]

metodo search

Cerca i record per somiglianza.

• Parametri:
  • query str | None: query in linguaggio naturale. Deve essere fornito quando query_vector viene omesso.
  • query_vector list[float] | None: incorporamento facoltativo di query precalcolate. Specificare esattamente uno dei valori query e query_vector.
  • k int: numero massimo di risultato da restituire. I valori espliciti devono essere almeno 1.
  • thread_id str | None: identificativo di ambito thread facoltativo. exact_thread_match=False lascia la dimensione thread non vincolata. exact_thread_match=True corrisponde esattamente al valore thread_id fornito. Se thread_id=None, corrisponde solo ai record senza ambito nella dimensione thread.
  • user_id str | None: identificativi facoltativi dell'ambito utente e agente. Il flag exact_*_match=False corrispondente lascia la dimensione non vincolata. exact_*_match=True corrisponde esattamente all'ID fornito. Se l'ID è None, corrisponde solo ai record senza ambito su tale dimensione.
  • agent_id str | None: identificativi facoltativi di ambito utente e agente. Il flag exact_*_match=False corrispondente lascia la dimensione non vincolata. exact_*_match=True corrisponde esattamente all'ID fornito. Se l'ID è None, corrisponde solo ai record senza ambito su tale dimensione.
  • exact_user_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • exact_agent_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • exact_thread_match bool: indica se ogni identificativo di ambito deve avere una corrispondenza esatta. False lascia la dimensione non vincolata. True corrisponde esattamente al valore fornito. Se il valore è None, corrisponde solo ai record con ambito non definito della dimensione.
  • record_types set[str] | None: set facoltativo di tipi di record ricercabili da includere. Se omessa, la ricerca DB copre messaggi, righe della tabella di memoria e profili attore. I profili attore contribuiscono al payload information, mentre le righe di messaggio e memoria contribuiscono al payload content. Durante la ricerca, i tipi di record profilo utilizzano il relativo identificativo attore per la dimensione ambito applicabile mentre le restanti dimensioni ambito funzionano come None.
  • metadata_filter dict[str, Any] | None: mapping facoltativo di metadati parziali. Un record corrisponde solo quando i relativi metadati memorizzati contengono tutte le chiavi e i valori richiesti. I dizionari nidificati vengono abbinati in modo ricorsivo. I valori di elenco vengono abbinati in base all'uguaglianza esatta anziché alla corrispondenza ricorsiva del subset, pertanto l'ordine e la lunghezza dell'elenco devono corrispondere.
• Restituzioni: coppie (record, distance) ordinate in base alla distanza crescente.
• Tipo restituito: list[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

Esempi

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'

Filtra in base a un valore di metadati scalare:

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

Filtra in base ai metadati nidificati:

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

Corrisponde esattamente a un valore di elenco, incluso l'ordine:

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

metodo search_async (asincrono)

Cerca i record in modo asincrono in base alla somiglianza vettoriale.

• Parametri:
  • query str | None: lo stesso testo di query accettato da search.
  • k int: conteggio massimo dei risultati accettato da search. I valori espliciti devono essere almeno 1.
  • query_vector list[float] | None: incorporamento facoltativo della stessa query precalcolata accettato da search.
  • thread_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • user_id str | None: gli stessi filtri di ambito opzionali accettati da search.
  • agent_id str | None: filtri di ambito opzionali uguali accettati da search.
  • exact_user_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_agent_match bool: flag della stessa corrispondenza esatta accettati da search.
  • exact_thread_match bool: flag della stessa corrispondenza esatta accettati da search.
  • record_types set[str] | None: filtro del tipo di record opzionale accettato da search.
• Restituzioni: coppie (record, distance) restituite dalla chiamata search sottostante.
• Tipo restituito: List[tuple[Record, float]]
• Raise: ValueError: se k è minore di 1.

metodo update

Aggiorna il contenuto dei record memorizzati, le integrazioni dei chunk e i valori dei metadati.

• Parametri:
  • record_type str: etichetta del tipo di record della riga da modificare, ad esempio "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile".
  • record_id str: identificativo della riga memorizzata da aggiornare.
  • testo str | None: il testo sostitutivo facoltativo è persistente nella colonna content. Passare None per cancellare il testo memorizzato e cancellare l'incorporamento memorizzato. Passare solo None o argomenti semantici omessi nella stessa chiamata. Passare "" per conservare il contenuto vuoto esplicito durante la cancellazione di qualsiasi incorporamento di chunk per quel record. Se omesso, il contenuto esistente rimane invariato.
  • index_text str | None: payload facoltativo di sola incorporazione. Se omesso, text viene incorporato.
  • incorporamento list[float] | ndarray | None: vettore di incorporamento precomputato facoltativo. Se fornito, questo viene utilizzato direttamente e non viene effettuata alcuna chiamata di incorporamento. Passare None per cancellare l'incorporamento memorizzato.
  • metadata dict[str, Any] | None: mapping dei metadati facoltativo serializzato in JSON e memorizzato in metadata.
• Restituzioni: numero di righe aggiornate (0 o 1). Restituisce 0 quando nessun record logico corrisponde a record_type e record_id.
• Tipo restituito: int.
• Aumenti: ValueError: se record_type non è supportato, se non viene fornito alcun payload di aggiornamento o se gli argomenti di aggiornamento semantico sono incompatibili.

Esempi

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'

Criterio schema

classe oracleagentmemory.core.SchemaPolicy

Basi: str, Enum

Criterio di creazione schema per le aree di memorizzazione di Oracle DB.

RICHIEDI_ESISTENTE

Verificare che lo schema gestito completo esista già e sia aggiornato. Non creare o modificare oggetti DB.

CREA_SE_EMPTY

Se non esistono oggetti gestiti, lo schema di bootstrap. Se gli oggetti esistono già, è necessario uno schema gestito completo e aggiornato.

CREA_SE_NECESSARIO

Crea solo oggetti gestiti mancanti, inclusi i metadati.

RICREA

Eliminare e ricreare tutti gli oggetti schema gestiti. Questo è distruttivo.