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

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_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]]
• Aumenti: 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 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.