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 (abstract)

Incorpora e rende persistenti i record di testo.

• Parametri:
  • contents list[str | None]: payload di testo da memorizzare. Questi valori vengono utilizzati anche come payload di incorporamento quando non viene fornito index_texts. Quando un elemento viene omesso (None), memorizza la risoluzione dalla chiave metadati "content" quando disponibile; altrimenti viene mantenuto il contenuto vuoto.
  • record_type str: etichetta del tipo di record per i record memorizzati, ad esempio "message" o "memory".
  • index_texts list[str]: payload facoltativi di sola incorporazione allineati a contents.
  • embeddings list[list[float]] | list[ndarray]: vettori di incorporamento opzionali precalcolati allineati a contents. Se fornito, i negozi utilizzano direttamente questi vettori e non chiamano l'incorporatore.
  • record_ids str | None | list[str] | list[None]: ID facoltativi dei record visibili al chiamante. Deve essere completamente fornito (uno per testo) o omesso per tutti i testi. Gli ID restituiti corrispondono a questi valori quando forniti.
  • thread_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • user_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • agent_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • ruoli str | None | list[str | None]: ruolo chat facoltativo per i record dei messaggi.
  • Indicatori data/ora str | None | list[str | None]: indicatore orario facoltativo o indicatori orari per record.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | None: mapping dei metadati facoltativo o mapping dei metadati per record. I metadati possono includere "content" come origine di fallback per i valori di testo omessi.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche dell'area di memorizzazione inoltrate da API di livello superiore.
• Restituzioni: inserire identificativi per ogni elemento di contenuto di input. Questi corrispondono a record_ids quando specificato; altrimenti memorizza gli identificativi di generazione.
• Tipo restituito: list[str]

Esempi

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

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 i messaggi e i record di memoria digitata.

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 all'archivio di memoria.

• Parametri:
  • contents list[str | None]: payload di testo da memorizzare. Questi valori vengono utilizzati anche per calcolare l'incorporamento a meno che non vengano forniti index_texts o embeddings. Quando un elemento viene omesso (None), memorizza la risoluzione dalla chiave metadati "content" quando disponibile; altrimenti viene mantenuto il contenuto vuoto.
  • record_type str: etichetta del tipo di record per i record memorizzati, ad esempio "message", "memory", guideline, fact o preference.
  • index_texts list[str]: payload alternativi facoltativi utilizzati solo per l'incorporamento o l'indicizzazione. Se specificato, deve avere la stessa lunghezza di contents.
  • embeddings list[list[float]] | list[ndarray]: vettori di incorporamento opzionali precalcolati allineati a contents. Se previsto, i negozi devono utilizzare direttamente questi vettori e non devono richiamare l'incorporatore. Se omesso, lo store utilizza l'embedder solo per i payload di indicizzazione non vuoti; le stringhe vuote esplicite vengono memorizzate senza incorporamenti di chunk.
  • record_ids str | None | list[str] | list[None]: ID facoltativi dei record visibili al chiamante. Deve essere completamente fornito (uno per testo) o omesso per tutti i testi. Gli ID restituiti corrispondono a questi valori quando forniti. Se omesso, il negozio genera gli ID lato client.
  • thread_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • user_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • agent_ids str | None | list[str | None]: identificativi di ambito facoltativi memorizzati con i record.
  • ruoli str | None | list[str | None]: ruolo chat facoltativo per i record dei messaggi.
  • timestamps str | None | list[str | None]: indicatori orari degli eventi forniti dal chiamante facoltativi.
  • 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 per i valori di testo omessi.
  • **store_kwargs (Qualsiasi): opzioni di scrittura specifiche per l'area di memorizzazione. Le chiavi supportate includono attualmente batch_size per l'esecuzione in batch di Oracle executemany.
• Restituzioni: inserire identificativi per ogni elemento di contenuto di input. Se specificato, corrisponde a record_ids. In caso contrario, memorizza gli ID generati dai resi.
• Tipo restituito: list[str]

Esempi

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

metodo add_agent

Aggiungere un record profilo agente.

• Parametri:
  • agent_id str: identificativo dell'agente.
  • informazioni str: informazioni in formato libero sull'agente.
• Restituzioni: identificativo del record profilo agente inserito.
• Tipo restituito: str

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.
• Restituzioni: identificativo del record del profilo utente inserito.
• Tipo restituito: str

Esempi

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

metodo delete

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

• Parametri:
  • record_type str: etichetta del tipo di record la cui tabella gestita deve essere mirata, ad esempio "message", "memory", "guideline", "fact" o "preference"
  • record_id str: identificativo della riga da rimuovere.
• Restituzioni: numero di righe rimosse (0 quando l'identificativo non è stato trovato).
• Tipo restituito: int.

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 vettoriali e chunk associate.

• Parametri: thread_id str: identificativo del thread le cui righe devono essere rimosse (incluse le righe figlio eliminate in cascata).
• Restituzioni: numero di righe di thread eliminate (0 o 1).
• Tipo restituito: int.

Esempi

store.delete_thread("c1")
0

metodo get

Recupera un messaggio o una memoria memorizzati in base all'identificativo.

• Parametri:
  • record_type str: etichetta del tipo di record che viene risolta in una riga vector-record gestita, ad esempio "message", "memory", "guideline", "fact" o "preference".
  • 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" o "preference").
  • limite int: numero massimo di dischi da restituire.
  • thread_id str | None: filtro thread-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record senza ambito nella dimensione thread.
  • 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 senza ambito nella dimensione utente.
  • agent_id str | None: filtro agente-ambito esatto. Se omesso, non viene applicato alcun filtro. Se impostato su None, vengono restituiti solo i record senza ambito nella dimensione agente.
  • 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]

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

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 da includere. Se omesso, la ricerca copre qualsiasi tipo di record.
  • 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 o preference.
  • record_id str: identificativo della riga del messaggio o della memoria 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.