Busca

Esta página apresenta os ajudantes de escopo voltados para o desenvolvedor junto com o tipo de resultado concreto da pesquisa Oracle.

Resolução do Escopo

Para cada campo de escopo, você pode fazer uma das três coisas:

• omita-o para usar o padrão dessa camada de API. Em assinaturas Python e em SearchScope, esse estado omitido é representado por NOT_SET_MARKER.
• especificar uma identificação concreta para utilizar esse valor;
• especifique None para indicar que o registro não tem escopo nessa dimensão. Por exemplo, agent_id=None significa que o registro não está vinculado a um agente.

Cada registro armazenado tem três campos de escopo independentes: user_id, agent_id e thread_id. Cada campo pode conter um ID concreto ou None.

Exemplos:

• thread_id=None significa que o registro não está vinculado a um thread.
• agent_id=None significa que o registro não está vinculado a um agente.
• user_id="u1", agent_id=None, thread_id=None significa que o registro tem como escopo o usuário u1, mas não qualquer agente ou thread específico.

As mesmas regras de escopo se aplicam a APIs de pesquisa síncronas e assíncronas.

Na tabela abaixo, ID significa qualquer user_id, agent_id ou thread_id, juntamente com seu flag de correspondência exata correspondente.

Pesquisar resolução de escopo por camada de API

Caso	thread.search()	OracleAgentMemory.search()	store.search()
ID omitido	Usa os padrões de thread: user_id e agent_id exatos, mais o thread_id atual com exact_thread_match=False.	Usa os padrões do cliente. user_id Omitido foi rejeitado. Omitido agent_id e thread_id permanecem amplos.	Usa os padrões de armazenamento: ID=None e exact_*_match=False, para que a dimensão não seja filtrada.
Valor explícito, incluindo None + exact_*_match=False	Essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.	Para user_id, rejeitado porque as pesquisas do cliente exigem escopo de usuário exato explícito. Para agent_id e thread_id, essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.	Essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.
ID Explícito + exact_*_match=True	Corresponde exatamente a esse ID.	Corresponde exatamente a esse ID.	Corresponde exatamente a esse ID.
Explícito None + exact_*_match=True	Corresponde somente a registros sem escopo nessa dimensão.	Corresponde somente a registros sem escopo nessa dimensão.	Corresponde somente a registros sem escopo nessa dimensão.

Use None explícito junto com exact_*_match=True quando quiser apenas registros sem escopo nessa dimensão e a API permitir. Omita o campo quando desejar o padrão da operação.

Filtragem de status do ciclo de vida

Todos os registros persistidos têm um status de ciclo de vida. O Search aceita include_invalid_results nas APIs de armazenamento, cliente e thread. Em APIs de cliente e thread, o padrão é NOT_SET_MARKER, o que resulta na inclusão de registros válidos e inválidos nos resultados da pesquisa. A API de armazenamento de nível inferior resolve seu padrão Booliano para o mesmo comportamento. Informe False para omitir registros cujo status seja RecordStatus.INVALID.

Expansão do gráfico

Informe num_hops de 0 a 5 para a API de pesquisa de armazenamento, cliente ou thread para anexar contexto de memória vinculado a cada resultado de memória direta. Traversal segue relações em qualquer direção, preserva a orientação da relação armazenada e retorna uma árvore de caminho mais curto através da sequência linked_results de cada registro. As correspondências de mensagem direta, documento e perfil do ator permanecem no conjunto de resultados classificados, mas não são expandidas por gráfico. Em particular, descrições de imagem pesquisáveis podem retornar registros de imagem sem tornar DOCUMENT um vértice de link de memória. Os filtros de escopo, metadados, tipo de registro e expiração aplicam-se a cada memória vinculada. include_invalid_results continua a controlar apenas correspondências de pesquisa de nível superior; não altera quais memórias vinculadas estão incluídas. max_linked_results limita o total de memórias vinculadas anexadas a cada resultado direto em todos os saltos. O padrão é 100; passe 0 para omitir o contexto vinculado.

Escopos

classe oracleagentmemory.apis.scope.Scope

Bases: object

Representa um escopo para inserção de informações ou pesquisas.

• Parâmetros:
  • id_usuário str | None
  • id_agente str | None
  • thread_id str | None

user_id

ID do usuário final. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que o escopo do usuário seja explícito. Nessas APIs, None só pode ser usado para direcionar registros sem escopo.

• Tipo: str | Nenhum

id_agente

ID do Agente. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação.

• Tipo: str | Nenhum

thread_id

ID de Thread. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação.

• Tipo: str | Nenhum

classe oracleagentmemory.apis.searchscope.SearchScope

Bases: Scope

Representa o escopo de uma consulta de pesquisa e, portanto, restringe o que pode ser retornado.

• Parâmetros:
  • id_usuário str | None
  • id_agente str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

ID do usuário final. Quando o valor exact_user_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão do usuário é irrestrita. NOT_SET_MARKER é substituído por um padrão específico da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que o escopo do usuário seja explícito. Nessas APIs, o destino None só destina registros sem escopo quando exact_user_match é resolvido como True.

• Tipo: str | Nenhum

id_agente

ID do Agente. Quando o valor exact_agent_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão do agente é irrestrita. NOT_SET_MARKER é substituído por um valor padrão, dependendo da operação que usa o escopo.

• Tipo: str | Nenhum

thread_id

ID de Thread. Quando o valor exact_thread_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão de thread é irrestrita. NOT_SET_MARKER é substituído por um valor padrão, dependendo da operação que usa o escopo.

• Tipo: str | Nenhum

exact_user_match

Se deve corresponder exatamente ao user_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão do usuário sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que isso permaneça True.

• Tipo: bool

exact_agent_match

Se deve corresponder exatamente ao agent_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão do agente sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação.

• Tipo: bool

exact_thread_match

Se deve corresponder exatamente ao thread_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão de thread sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação.

• Tipo: bool

Configuração de Pesquisa

classe oracleagentmemory.core.MemorySearchConfig

Bases: ISearchConfig

Configuração básica para comportamento de pós-pesquisa de memória.

• Parâmetros:
  • token_budget int | None
  • soft_token_budget int | None

Tamanho de destino opcional para saída de pesquisa formatada.

Os resultados completos são mantidos em ordem de classificação até o primeiro resultado que atinge ou excede esse orçamento. O primeiro resultado é, portanto, retido quando nenhum token_budget rígido o impede de ser retornado.

Limite rígido opcional para o tamanho estimado da saída de pesquisa formatada.

Os resultados completos são mantidos em ordem de classificação enquanto sua estimativa cumulativa se encaixa no orçamento. Se o primeiro resultado não for adequado, nenhum resultado será retornado.

classe oracleagentmemory.core.TopKMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Configuração de pesquisa com um máximo fixo de resultados diretos.

• Parâmetros:
  • token_budget int | None
  • soft_token_budget int | None
  • restaurante IReranker | None
  • reranker_max_candidates int
  • max_results int

Número máximo de resultados diretos recuperados antes da nova classificação.

classe oracleagentmemory.core.PruningEvaluationMode

Bases: str, Enum

Controla como os resultados da pesquisa são extensivamente avaliados durante a poda.

EXHAUSTIVE = 'exaustivo'

Avalie cada resultado do candidato individualmente. Isso fornece a avaliação mais completa, mas tem a maior latência e uso de LLM.

= 'estendido'

Avalie uma parte mais ampla dos resultados antes de decidir quais reter, ao custo de latência adicional e uso do LLM.

FAST = 'rápido'

Priorize a baixa latência interrompendo a avaliação antecipadamente quando for improvável que outras verificações alterem quais resultados são retidos.

classe oracleagentmemory.core.PruningMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Configuração de pesquisa que remove resultados diretos menos relevantes.

Os limites de resultado direto são fornecidos em cada pesquisa ou chamada de cartão de contexto e aplicados antes da reclassificação e da remoção.

• Parâmetros:
  • token_budget int | None
  • soft_token_budget int | None
  • restaurante IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • fração_protegida float
  • pruner ILlm

Quão extensivamente os resultados da pesquisa são avaliados durante a poda.

Quando omitido, PruningEvaluationMode.FAST é usado.

Número de regiões de resultados classificados avaliadas no modo FAST ou EXTENDED.

Este parâmetro não pode ser definido quando evaluation_mode é PruningEvaluationMode.EXHAUSTIVE.

Fração de resultados diretos de maior classificação protegidos da poda.

Por exemplo, o 0.1 protege os 10% principais de resultados diretos.

O LLM usado para decidir quais resultados diretos remover.

Resultados

classe oracleagentmemory.core.SearchResultFormatConfig

Bases: object

Controlar opções de renderização de resultados de pesquisa portáteis.

Implementações podem fornecer uma subclasse com opções de renderização adicionais.

• Parâmetros: include_invalid_results bool – Se registros vinculados inválidos incluem seu conteúdo. Quando False, as ramificações somente inválidas são omitidas, enquanto os registros inválidos em um caminho para um registro válido mantêm seu status e contexto de link. Omita o uso de True.

classe oracleagentmemory.core.OracleSearchResultFormatConfig

Bases: SearchResultFormatConfig

Controlar opções de renderização de resultados de pesquisa da Oracle.

• Parâmetros:
  • show_thread_id bool – Se o identificador de thread do registro será incluído. Omita o uso de False.
  • show_distance bool – Se deve incluir relevância estimada. Omita o uso de False.
  • show_timestamp bool – Se deseja incluir carimbos de data/hora do registro. Omita o uso de True.
  • show_role bool – Se as funções de mensagem devem ser incluídas. Omita o uso de True.
  • show_user_id bool – Se deseja incluir identificadores de usuário de registro. Omita o uso de False.
  • show_agent_id bool – Se deseja incluir identificadores de agente de registro. Omita o uso de False.
  • show_status bool – Se deve incluir status de ciclo de vida de registro. Omita o uso de True.
  • show_metadata bool – Se os metadados do chamador e o motivo de invalidação de memória devem ser incluídos, quando presentes. Cada entrada usa sua chave de metadados como uma tag XML e renderiza seu valor como uma string. Omita o uso de False.
  • include_invalid_results bool

classe oracleagentmemory.core.OracleSearchResult

Bases: SearchResult

Resultado da pesquisa retornado por um thread Oracle.

• Parâmetros:
  • distância float – Distância do vetor de consulta (menor é melhor).
  • record Record – Um objeto de registro que contém as informações de metadados sobre a entrada persistente.
  • id str | None – Identificador opcional associado ao registro armazenado.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None – Resultados filhos vinculados a gráficos opcionais. Cada par contém o RecordRelation armazenado e o resultado alcançado através dele.
  • format_config SearchResultFormatConfig – Opções de renderização padrão usadas por formatted_content e por format_content() quando nenhuma opção é fornecida.

propriedade content

• Tipo de Retorno: str
• Descrição: Retorna o conteúdo textual principal do registro correspondente.

método format_content

Renderize este resultado e seu contexto de gráfico como texto de prompt seguro para XML.

• Parâmetros: format_config SearchResultFormatConfig – Opções de renderização para esta chamada. Omita para usar a configuração padrão deste resultado. Em uma configuração fornecida, as opções omitidas são retornadas às opções correspondentes nessa configuração padrão.
• Retorna: renderização de resultado segura para XML.
• Tipo de retorno: str

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna a renderização padrão XML-safe usada em prompts.

• Retorna: Renderização segura para XML que usa a configuração padrão deste resultado.
• Tipo de retorno: str

propriedade id

• Tipo de Retorno: str

  Nenhum

• Descrição: Retorna o identificador estável do registro correspondente, quando disponível.

propriedade linked_results

• Tipo de Retorno: list[tuple[RecordRelation, SearchResult]]
• Descrição: Retorna os resultados vinculados na árvore de caminho mais curto recursiva.

propriedade metadata

• Tipo de Retorno: dict[str, Any]

  Nenhum

• Descrição: Retorne metadados de registro, se disponíveis.

propriedade record

• Tipo de Retorno: Registro
• Descrição: Retorna o registro correspondente.

O valor retornado pode ser uma subclasse Record simples ou ScopedRecord. Use isinstance(result.record, ScopedRecord) antes de ler identificadores de escopo público.

propriedade status

• Tipo de Retorno: RecordStatus

  Nenhum

• Descrição: Retorna o status do ciclo de vida do registro correspondente.

propriedade timestamp

• Tipo de Retorno: str

  Nenhum

• Descrição: Retorna o timestamp do registro, se disponível.