Lojas e Esquema

Esta página apresenta as abstrações do armazenamento principal e os controles de esquema usados pelo SDK de Memória do Oracle Agent.

API da loja

classe oracleagentmemory.core.OracleMemoryStore

Bases: IMemoryStore

Interface de armazenamento comum usada pelo OracleAgentMemory.

Uma implementação de loja é responsável por persistir registros de texto e executar uma pesquisa de similaridade sobre eles. Os pontos de entrada síncronos e assíncronos são definidos para que as APIs de nível superior possam expor superfícies síncronas/assíncronas correspondentes sem duplicar a lógica específica da loja.

method search (abstract)

Pesquisar registros por similaridade.

• Parâmetros:
  • query str | None – Consulta em linguagem natural. Deve ser fornecido quando query_vector for omitido.
  • query_vector list[float] | None – Incorporação de consulta pré-calculada opcional. Exatamente um dos query e query_vector deve ser fornecido.
  • k int – Número máximo de resultados a ser retornado. Os valores explícitos devem ser pelo menos 1.
  • thread_id str | None – Escopo do thread opcional.
  • user_id str | None – Filtros de escopo de usuário e agente opcionais.
  • agent_id str | None – Filtros de escopo de usuário e agente opcionais.
  • exact_user_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • exact_agent_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • exact_thread_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • record_types set[str] | None – Conjunto opcional de tipos de registro a incluir.
  • metadata_filter dict[str, Any] | None – Mapeamento de metadados parcial opcional. Um registro só corresponde quando seus metadados armazenados contêm todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• Retorna: pares de (record, distance) classificados por distância crescente.
• Tipo de retorno: list[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

Exemplos de

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'

Filtrar em um valor de metadados escalar:

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

Filtrar em metadados aninhados:

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

Corresponder exatamente um valor de lista, incluindo a ordem:

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

Armazenamento do Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Persistência baseada em banco de dados para mensagens, memórias e perfis de atores.

Crie um armazenamento do Oracle DB.

• Parâmetros:
  • embedder IEmbedder | None – Embedder usado para tipos de registro vetorizados. Pode ser None quando os chamadores sempre fornecem vetores pré-calculados em add, update e search.
  • pool Any – Conexão ou pool do Oracle DB. A transmissão de uma conexão bruta ativa o modo de sessão única para esta instância de armazenamento: as chamadas de armazenamento simultâneas são serializadas localmente para preservar as suposições de bloqueio de linha e transação usadas pelas operações de gravação. Use um pool de conexões para solicitações simultâneas.
  • schema_policy SchemaPolicy | str – Modo de configuração do esquema. O padrão é exigir um esquema gerenciado existente e atualizado e não executar alterações de DDL. Use SchemaPolicy.CREATE_IF_NECESSARY para preencher objetos ausentes ou SchemaPolicy.RECREATE para eliminar e recriar objetos gerenciados.
  • vector_dim int – Dimensão de incorporação para criação de esquema quando colunas VECTOR são criadas.
  • table_name_prefix str – Prefixo opcional adicionado aos nomes de tabelas/índices gerenciados.

método add_agent

Adicionar um registro de perfil do agente.

• Parâmetros:
  • agent_id str – Identificador do agente.
  • informações str – Informações de formato livre sobre o agente. Esse texto é armazenado como conteúdo do perfil e usado para criar a linha de incorporação de perfil em RECORD_CHUNKS.
• Devoluções: Identificador do registro de perfil do agente inserido.
• Tipo de retorno: str

Observações

Os registros de perfil do agente não têm escopo. O identificador de registro público inserido é o mesmo valor informado como agent_id.

Exemplos de

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

método add_user

Adicionar um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador do usuário.
  • informações str – Informações de formato livre sobre o usuário. Esse texto é armazenado como conteúdo do perfil e usado para criar a linha de incorporação de perfil em RECORD_CHUNKS.
• Devoluções: Identificador do registro de perfil de usuário inserido.
• Tipo de retorno: str

Observações

Os registros de perfil do usuário não têm escopo. O identificador de registro público inserido é o mesmo valor informado como user_id.

Exemplos de

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

método delete

Excluir uma linha gerenciada e suas linhas de bloco por identificador.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro a ser excluído. Os tipos de suporte incluem "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" e "agent_profile".
  • record_id str – Identificador a excluir.
  • cascade bool – Quando True, expanda os destinos de nível superior suportados, como perfis de ator, em suas linhas filho com escopo dentro da mesma transação. Para um destino user-profile ou agent-profile, isso exclui primeiro as linhas de thread pertencentes, que removem suas linhas de mensagem com escopo de thread e de tabela de memória e, em seguida, exclui todas as mensagens com escopo de ator diretamente restantes e linhas semelhantes à memória (memory, guideline, fact, preference). Essa limpeza com escopo ainda é executada quando a linha do perfil correspondente já está ausente.
• Retorna: Número de destinos de nível superior solicitados removidos, geralmente 0 ou 1. As linhas filho em cascata não são contadas separadamente, portanto, ainda pode ser 0 quando um perfil de ator ausente aciona a limpeza com escopo.
• Tipo de retorno: int

Observações

A operação é executada dentro de uma transação. Quando cascade está ativado para um destino de nível superior suportado, a exclusão do perfil e todas as exclusões filho com escopo são submetidas a commit ou submetidas a rollback juntas.

Exemplos de

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

método delete_thread

Excluir um thread e suas linhas armazenadas associadas.

• Parâmetros: thread_id str – Identificador do thread cujas linhas devem ser removidas, incluindo a linha do thread, as linhas filho dependentes e a limpeza explícita da linha de bloco.
• Retorna: Número de linhas de thread excluídas (0 ou 1).
• Tipo de retorno: int

Observações

Use esta operação quando precisar de limpeza em cascata com escopo de thread. No armazenamento suportado pelo BD, a exclusão do thread remove a linha do thread gerenciado juntamente com as linhas de mensagem e memória associadas, além das linhas de bloco de registro mantidas para recuperação. Isso é mais amplo do que uma exclusão no nível da mensagem, o que remove apenas a linha da mensagem bruta. A exclusão do thread remove as linhas dependentes de mensagem e memória referenciadas de THREAD junto com as linhas RECORD_CHUNKS correspondentes na mesma transação.

Exemplos de

store.delete_thread("c1")
0

método get

Recuperar um registro armazenado por identificador.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro resolvendo para uma linha gerenciada, como "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile".
  • record_id str – Identificador a ser pesquisado.
• Retorna: Registro preenchido com metadados decodificados quando encontrado; caso contrário, None.
• Tipo de retorno: Registro | Nenhum

Exemplos de

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étodo list

Enumerar registros persistidos para um tipo de registro.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro (por exemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile").
  • limit int | None – Número máximo opcional de registros a serem retornados. Quando omitido, o armazenamento usa seu limite de listagem padrão. Passe None para desativar esse limite e retornar todos os registros correspondentes.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo thread_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram esse filtro.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo user_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram esse filtro.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo agent_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram este filtro.
  • metadata_filter dict[str, Any] | None – Filtro de metadados. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros sem metadados armazenados são retornados. Quando definidos como um dict, os metadados armazenados devem conter todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• Devoluções: Registros ordenados por ordem de inserção.
• Tipo de retorno: list[Registro]

Observações

"user_profile" e "agent_profile" são tipos de registro sem escopo. Para esses tipos de registro, thread_id, user_id e agent_id são ignorados e a identidade do ator permanece na record.id.

Exemplos de

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étodo list_thread_messages

Retornar mensagens persistidas para um tópico.

• Parâmetros:
  • thread_id str – Identificador do thread cujas mensagens devem ser retornadas.
  • last_n int | None – Número opcional de mensagens mais recentes a serem retornadas.
• Devoluções: Registros de mensagem ordenados por ordem de inserção.
• Tipo de retorno: list[MessageRecord]

Exemplos de

store.list_thread_messages("c1")
[]

método search

Pesquisar registros por similaridade.

• Parâmetros:
  • query str | None – Consulta em linguagem natural. Deve ser fornecido quando query_vector for omitido.
  • query_vector list[float] | None – Incorporação de consulta pré-calculada opcional. Exatamente um dos query e query_vector deve ser fornecido.
  • k int – Número máximo de resultados a ser retornado. Os valores explícitos devem ser pelo menos 1.
  • thread_id str | None – Identificador de escopo de thread opcional. exact_thread_match=False deixa a dimensão de thread sem restrições. exact_thread_match=True corresponde exatamente ao thread_id fornecido. Se thread_id=None, ele corresponderá apenas aos registros sem escopo na dimensão de thread.
  • user_id str | None – Identificadores de escopo de usuário e agente opcionais O flag exact_*_match=False correspondente deixa essa dimensão sem restrições. exact_*_match=True corresponde exatamente ao ID fornecido. Se o ID for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • agent_id str | None – Identificadores de escopo de usuário e agente opcionais. O flag exact_*_match=False correspondente deixa essa dimensão sem restrições. exact_*_match=True corresponde exatamente ao ID fornecido. Se o ID for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_user_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_agent_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_thread_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • record_types set[str] | None – Conjunto opcional de tipos de registro pesquisáveis a serem incluídos. Quando omitida, a pesquisa do BD abrange mensagens, linhas da tabela de memória e perfis de ator. Os perfis de ator contribuem com o payload information, enquanto as linhas de mensagem e memória contribuem com o payload content. Durante a pesquisa, os tipos de registro de perfil usam seu identificador de ator para a dimensão de escopo aplicável, enquanto as dimensões de escopo restantes se comportam como None.
  • metadata_filter dict[str, Any] | None – Mapeamento de metadados parcial opcional. Um registro só corresponde quando seus metadados armazenados contêm todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• Retorna: pares de (record, distance) classificados por distância crescente.
• Tipo de retorno: list[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

Exemplos de

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'

Filtrar em um valor de metadados escalar:

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

Filtrar em metadados aninhados:

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

Corresponder exatamente um valor de lista, incluindo a ordem:

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étodo update

Atualize o conteúdo do registro armazenado, as incorporações de chunk e os valores de metadados.

• Parâmetros:
  • record_type str – Rótulo do tipo de registro da linha que está sendo modificada (por exemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile")
  • record_id str – Identificador da linha armazenada a ser atualizada.
  • text str | None – Texto de substituição opcional persistido na coluna content. Passe None para limpar o texto armazenado e limpar a incorporação armazenada. Informe somente None ou argumentos semânticos omitidos na mesma chamada. Informe "" para preservar conteúdo vazio explícito ao limpar qualquer incorporação de chunk para esse registro. Quando omitido, o conteúdo existente é deixado inalterado.
  • index_text str | None – Payload somente de incorporação opcional. Quando omitido, text é incorporado.
  • embedding list[float] | ndarray | None – Vetor de incorporação pré-computado opcional. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Passe None para limpar a incorporação armazenada.
  • metadata dict[str, Any] | None – Mapeamento de metadados opcional serializado para JSON e armazenado em metadata.
• Retorna: Número de linhas atualizadas (0 ou 1). Retorna 0 quando nenhum registro lógico corresponde a record_type e record_id.
• Tipo de retorno: int
• Gera: ValueError – Se record_type não for suportado, se nenhum payload de atualização for fornecido ou se os argumentos de atualização semântica forem incompatíveis.

Exemplos de

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'

Política de Esquema

classe oracleagentmemory.core.SchemaPolicy

Bases: str, Enum

Política de criação de esquema para armazenamentos do Oracle DB.

REQUER_EXISTENTE

Valide se o esquema gerenciado completo já existe e está atualizado. Não crie ou modifique objetos do BD.

CRIAR_SE_VAZIO

Se não houver objetos gerenciados, o esquema de bootstrap. Se já existirem objetos, exija um esquema gerenciado completo e atualizado.

CRIAR_SE_NECESSÁRIO

Crie somente objetos gerenciados ausentes, incluindo metadados.

RECRIAR

Elimine e recrie todos os objetos de esquema gerenciados. Isso é destrutivo.