検索

このページでは、開発者向けスコープ指定ヘルパーと、具体的なOracle検索結果タイプを示します。

スコープ解決

スコープ・フィールドごとに、次の3つのうちのいずれかを実行できます。

• そのAPIレイヤーのデフォルトを使用するように省略します。Python署名およびSearchScopeでは、この省略された状態はNOT_SET_MARKERで表されます。
• その値を使用する具体的なIDを指定します。
• Noneを指定すると、そのディメンションでレコードのスコープが解除されます。たとえば、agent_id=Noneは、レコードが1つのエージェントに関連付けられていないことを意味します。

各ストアド・レコードには、user_id、agent_idおよびthread_idの3つの独立したスコープ・フィールドがあります。各フィールドは、具象IDまたはNoneを保持できます。

例:

• thread_id=Noneは、レコードが1つのスレッドに関連付けられていないことを意味します。
• agent_id=Noneは、レコードが1つのエージェントに関連付けられていないことを意味します。
• user_id="u1", agent_id=None, thread_id=Noneは、レコードがユーザーu1にスコープ指定されるが、特定のエージェントまたはスレッドにはスコープ指定されないことを意味します。

同期検索APIと非同期検索APIの両方に、同じ範囲指定ルールが適用されます。

次の表では、IDは、対応する完全一致フラグとともに、user_id、agent_idまたはthread_idのいずれかを意味します。

APIレイヤーによるスコープ解決の検索

ケース	thread.search()	OracleAgentMemory.search()	store.search()
IDが省略されました	スレッドのデフォルト値(正確なuser_idとagent_id、および現在のthread_idとexact_thread_match=False)を使用します。	クライアントのデフォルトを使用します。省略されたuser_idは拒否されます。省略されたagent_idおよびthread_idは広範囲に保たれます。	ディメンションがフィルタされないように、ストア・デフォルト(ID=Noneおよびexact_*_match=False)を使用します。
明示的な値(None + exact_*_match=Falseを含む)	そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。	user_idの場合、クライアント検索には明示的な正確なユーザー・スコープ指定が必要であるため、拒否されます。agent_idおよびthread_idの場合、そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。	そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。
明示的なID + exact_*_match=True	そのIDに正確に一致します。	そのIDに正確に一致します。	そのIDに正確に一致します。
明示的なNone + exact_*_match=True	そのディメンションでスコープ指定されていないレコードのみに一致します。	そのディメンションでスコープ指定されていないレコードのみに一致します。	そのディメンションでスコープ指定されていないレコードのみに一致します。

明示的なNoneをexact_*_match=Trueとともに使用すると、そのディメンションで有効範囲なしのレコードのみが許可され、APIで許可されます。かわりに操作をデフォルトにする場合は、フィールドを省略します。

ライフサイクル・ステータスのフィルタリング

すべての永続レコードにライフサイクル・ステータスがあります。Searchは、ストア、クライアントおよびスレッドAPIでinclude_invalid_resultsを受け入れます。クライアントおよびスレッドAPIでは、デフォルトでNOT_SET_MARKERに設定され、検索結果に有効および無効なレコードを含めるように解決されます。下位レベルのストアAPIは、ブールのデフォルトを同じ動作に解決します。Falseを渡して、ステータスがRecordStatus.INVALIDのレコードを省略します。

グラフの拡張

0から5までのnum_hopsをストア、クライアントまたはスレッド検索APIに渡して、リンクされたメモリー・コンテキストを各ダイレクト・メモリー結果にアタッチします。トラバーサルは、どちらの方向でもリレーションに従い、格納されたリレーションの方向を保持し、各レコードのlinked_resultsシーケンスを通して最短パス・ツリーを返します。ダイレクト・メッセージ、ドキュメントおよびアクター・プロファイルの一致は、ランク付けされた結果セットに残りますが、グラフは展開されません。特に、検索可能なイメージ記述は、DOCUMENTをメモリーリンク頂点にすることなくイメージ・レコードを返すことができます。スコープ・フィルタ、メタデータ・フィルタ、レコード・タイプ・フィルタおよび有効期限フィルタは、リンクされているすべてのメモリーに適用されます。include_invalid_resultsは、引き続き最上位の検索一致のみを制御します。どのリンクされたメモリーが含まれるかは変更されません。max_linked_resultsは、すべてのホップで各直接結果にアタッチされたリンクされたメモリーの合計を上限とします。デフォルトは100で、リンクされたコンテキストを省略する場合は0を渡します。

スコープ

クラス oracleagentmemory.apis.scope.Scope

ベース: object

情報の挿入または検索のスコープを表します。

• パラメータ:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

エンドユーザーのID。NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、ユーザー・スコープを明示する必要がある場合があります。これらのAPIでは、Noneを使用して、スコープなしレコードのみをターゲットにできます。

• タイプ: str | None

エージェントID

エージェントID NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。

• タイプ: str | None

スレッドID

スレッドID。NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。

• タイプ: str | None

クラス oracleagentmemory.apis.searchscope.SearchScope

ベース: Scope

検索問合せのスコープを表すため、返される内容を制限します。

• パラメータ:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

エンドユーザーのID。解決されたexact_user_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、ユーザー・ディメンションは制約されません。NOT_SET_MARKERは、操作固有のデフォルトに置き換えられます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、ユーザー・スコープを明示する必要がある場合があります。これらのAPIでは、exact_user_matchがTrueに解決された場合、Noneはスコープなしレコードのみをターゲットとします。

• タイプ: str | None

エージェントID

エージェントID 解決されたexact_agent_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、エージェント・ディメンションは制約されません。NOT_SET_MARKERは、スコープを使用する操作に応じてデフォルト値に置き換えられます。

• タイプ: str | None

スレッドID

スレッドID。解決されたexact_thread_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、スレッド・ディメンションは制約されません。NOT_SET_MARKERは、スコープを使用する操作に応じてデフォルト値に置き換えられます。

• タイプ: str | None

完全一致

解決されたuser_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、ユーザー・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、これをTrueのままにする必要がある場合があります。

• タイプ: bool

完全一致エージェント

解決されたagent_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、エージェント・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。

• タイプ: bool

完全スレッド一致

解決されたthread_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、スレッド・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。

• タイプ: bool

構成の検索

クラス oracleagentmemory.core.MemorySearchConfig

ベース: ISearchConfig

メモリー検索後の動作の基本構成。

• パラメータ:
  • token_budget int | None
  • soft_token_budget int | None

書式設定された検索出力のオプションのターゲット・サイズ。

完全な結果は、この予算に達するか超える最初の結果を通してランク順に保持されます。したがって、ハードtoken_budgetが戻されない場合は、最初の結果が保持されます。

フォーマット済検索出力の見積サイズに対するオプションのハード制限。

累積見積が予算に適合する間、完全な結果はランク順に保持されます。最初の結果が収まらない場合、結果は返されません。

クラス oracleagentmemory.core.TopKMemorySearchConfig

ベース: _RerankingMemorySearchConfig

直接結果の最大値が固定された検索構成。

• パラメータ:
  • token_budget int | None
  • soft_token_budget int | None
  • リランカ IReranker | None
  • reranker_max_candidates int
  • max_results int

再ランク付け前に取得された直接結果の最大数。

クラス oracleagentmemory.core.PruningEvaluationMode

ベース: str、Enum

プルーニング中に検索結果を広範囲に評価する方法を制御します。

EXHAUSTIVE = 'EXHAUSTIVE'

すべての候補者結果を個別に評価します。これにより、最も完全な評価が提供されますが、レイテンシとLLMの使用率が最も高くなります。

拡張 = 'EXTENDED'

追加レイテンシとLLMの使用を犠牲にして、保持する結果を決定する前に、結果の広範な部分を評価します。

FAST = 'FAST'

保持される結果を変更する可能性が低い追加のチェックで評価を早期に停止することで、低レイテンシに優先順位を付けます。

クラス oracleagentmemory.core.PruningMemorySearchConfig

ベース: _RerankingMemorySearchConfig

関連性の低い直接結果を削除する検索構成。

直接結果制限は、検索またはコンテキスト・カード・コールごとに指定され、再ランク付けおよびプルーニングの前に適用されます。

• パラメータ:
  • token_budget int | None
  • soft_token_budget int | None
  • リランカ IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

プルーニング中に検索結果がどの程度広範囲に評価されるか。

省略すると、PruningEvaluationMode.FASTが使用されます。

FASTまたはEXTENDEDモードで評価されたランク付け結果リージョンの数。

evaluation_modeがPruningEvaluationMode.EXHAUSTIVEの場合、このパラメータは設定できません。

プルーニングから保護される最高位の直接結果の部分。

たとえば、0.1は、直接結果の上位10%を保護します。

どの直接的な結果を削除するかを決定するために使用されるLLM。

結果

クラス oracleagentmemory.core.SearchResultFormatConfig

ベース: object

移植可能な検索結果のレンダリングオプションを制御します。

実装では、サブクラスに追加のレンダリング・オプションを提供できます。

• パラメータ: include_invalid_results bool– 無効なリンク・レコードにその内容が含まれているかどうか。Falseの場合、無効のみのブランチは省略されますが、有効なレコードへのパスの無効なレコードはステータスおよびリンク・コンテキストを保持します。Trueの使用を省略します。

クラス oracleagentmemory.core.OracleSearchResultFormatConfig

ベース: SearchResultFormatConfig

Oracleの検索結果レンダリング・オプションを制御します。

• パラメータ:
  • show_thread_id bool– レコードのスレッド識別子を含めるかどうか。Falseの使用を省略します。
  • show_distance bool– 推定関連性を含めるかどうか。Falseの使用を省略します。
  • show_timestamp bool– レコードのタイムスタンプを含めるかどうか。Trueの使用を省略します。
  • show_role bool– メッセージ役割を含めるかどうか。Trueの使用を省略します。
  • show_user_id bool– レコードユーザー識別子を含めるかどうか。Falseの使用を省略します。
  • show_agent_id bool– レコードエージェント識別子を含めるかどうか。Falseの使用を省略します。
  • show_status bool– レコードのライフサイクルステータスを含めるかどうか。Trueの使用を省略します。
  • show_metadata bool– 呼び出し元のメタデータとメモリー無効化の理由(存在する場合)を含めるかどうか。各エントリは、メタデータ・キーをXMLタグとして使用し、その値を文字列としてレンダリングします。Falseの使用を省略します。
  • include_invalid_results bool

クラス oracleagentmemory.core.OracleSearchResult

ベース: SearchResult

Oracleスレッドによって返された検索結果。

• パラメータ:
  • distance float– 問合せベクトルからの距離(小さい方が良い)。
  • record Record– 永続化されたエントリに関するメタデータ情報を含むレコードオブジェクト。
  • id str | None– 格納されたレコードに関連付けられたオプションの識別子。
  • linked_results list tuple[[RecordRelation, SearchResult]] | None– オプションのグラフリンク子結果。各ペアには、格納されたRecordRelationとそれによって到達した結果が含まれます。
  • format_config SearchResultFormatConfig– オプションが指定されていない場合にformatted_contentおよびformat_content()によって使用されるデフォルトのレンダリングオプション。

プロパティ content

• 戻りタイプ: str
• 説明:一致したレコードのプライマリ・テキスト・コンテンツを返します。

メソッド format_content

この結果とそのグラフ・コンテキストをXMLセーフ・プロンプト・テキストとしてレンダリングします。

• パラメータ: format_config SearchResultFormatConfig– このコールのレンダリング・オプション。この結果のデフォルト構成の使用を省略します。指定された構成では、省略されたオプションは、そのデフォルト構成の対応するオプションにフォールバックします。
• 戻り値: XMLセーフな結果レンダリング。
• 戻り型: str

property formatted_content

• 戻りタイプ: str

• 説明:プロンプトで使用されるデフォルトのXMLセーフ・レンダリングを返します。

• 戻り値:この結果のデフォルト構成を使用するXMLセーフ・レンダリング。
• 戻り型: str

プロパティー id

• 戻りタイプ: str

  なし

• 説明:一致したレコードの安定した識別子(使用可能な場合)を返します。

property linked_results

• 戻りタイプ: list[tuple[RecordRelation、 SearchResult]]
• 説明:リンクされた結果を、再帰的な最短パス・ツリーで返します。

property metadata

• 戻りタイプ: dict[str、 Any]

  なし

• 説明:レコード・メタデータ(使用可能な場合)を返します。

property record

• 戻りタイプ: レコード
• 説明:一致したレコードを返します。

戻り値は、プレーンなRecordまたはScopedRecordサブクラスです。パブリック・スコープ識別子を読み取る前に、isinstance(result.record, ScopedRecord)を使用します。

property status

• 戻り型: RecordStatus

  なし

• 説明:一致したレコードのライフサイクル・ステータスを返します。

property timestamp

• 戻りタイプ: str

  なし

• 説明:レコード・タイムスタンプ(使用可能な場合)を返します。