スレッド

このページでは、開発者向けのメッセージ・ヘルパー・タイプとともに、具体的なOracleスレッド・ハンドルを示します。

Oracleスレッド

クラス oracleagentmemory.core.OracleThread

ベース: IThread

Oracleストアに支えられたスレッド。

この実装では、スレッド・メッセージと手動で追加したメモリーの両方を埋め込んで格納し、格納されているすべてのレコードの類似性検索をサポートします。

ノート:

• メッセージは個々のレコードとして格納されます(メッセージごとに1つのレコード)。
• 検索は、現在のスレッドに制限することも、任意のスレッド(クライアント制御)から結果を返すこともできます。

新しいOracleThreadインスタンスを作成します。

• パラメータ:
  • store OracleMemoryStore– 埋込みレコードの永続化に使用される共有ストア・バックエンド。
  • thread_id str– スレッド識別子。指定しない場合、UUIDが生成されます。
  • user_id str– スレッドに関連付けられたユーザー識別子。省略すると、UUIDが生成されます。
  • agent_id str– スレッドに関連付けられたエージェント識別子。省略すると、UUIDが生成されます。
  • metadata dict[str, Any] | None– スレッドに関連付けられたオプションのJSONに似たメタデータ。
  • persist_messages_in_config bool– _to_configに最新のrawメッセージスナップショットを含めるかどうか。スレッド構成を介してメッセージ表コンテンツをエクスポートしないように、DBストアを使用するスレッドに対して自動的にFalseに設定されます。
  • LLM ILlm | None– メモリー抽出およびコンテキストサマリー更新に使用されるオプションのLLMアダプタ。add_messagesを指定すると、追加された各メッセージから関連するメモリーが抽出され、型付きメモリー・レコード("memory"、"guideline"、"fact"または"preference")として格納されます。
  • memory_extraction_config MemoryExtractionConfig– オプションのスレッドレベルのメモリー抽出構成。これを使用して、抽出モード、サマリー動作、抽出制限、自動抽出がまったく有効かどうかなどの自動抽出設定を制御します。このグループ化された構成または非推奨のインライン抽出パラメータのいずれかを渡します。両方は渡しません。省略すると、スタンドアロンのOracleThread()は抽出フィールドにSDKのデフォルトを使用し、コンテキスト・サマリーを有効のままにします。

  • memory_extraction_window int–

    抽出中にLLMにコンテキストとして提供する最新のメッセージ(新しく追加されたメッセージを含む)の数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。デフォルトは-1です。

    非推奨

    バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨になり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • context_summary_update_frequency int–

    抽出コンテキスト・サマリーを更新するまでのメッセージ数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ要約されます。デフォルトは-1です。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • memory_extraction_frequency int–

    メモリー抽出がトリガーされるまでのメッセージの数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • memory_extraction_token_limit int–

    メモリー抽出およびサマリー更新の実行に使用されるLLMプロンプトの最大サイズ(トークン単位)。長いプロンプトは切り捨てられます。負または0の場合、プロンプトの切捨ては無効になります。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • context_card_token_limit int– コンテキスト・カードに含まれるサマリーおよびトピック・リストの作成に使用されるLLMプロンプトの最大入力トークン予算。デフォルトは100_000で、0以下の値はプロンプトの切捨てを無効にします。
  • context_card_type_search_concurrency int– min_relevant_results_by_typeを使用してコンテキスト・カードを構築するときに同時に実行するメモリーに似たレコード検索の最大数。デフォルトは5です。
  • max_message_token_length int–LLMでバックアップされたメモリーの抽出およびコンテキストサマリーの更新時に使用される各メッセージのプロンプトタイムコピーの最大サイズ(トークン単位)。格納されたメッセージ・コンテンツは変更されません。負または0の場合、プロンプトタイム短縮は実行されません。LLMが指定されている場合は、切り捨てられるのではなく、サイズ超過のプロンプト・コピーが要約されます。
  • message_shortening_input_token_limit int– オーバーサイズのプロンプトコピーを短縮するときにLLMに送信されたメッセージ抜粋の最大サイズ(トークン単位)。デフォルトは30_000トークンです。負または0の場合、LLMベースの短縮時にアウトバウンド境界は適用されません。

  • enable_context_summary bool–

    スレッドのコンパクトな実行サマリーを保持するかどうか。有効にしてllmを指定すると、context_summary_update_frequencyに従ってサマリーが更新されます。現在の要約は、記憶を抽出するときにコンテキストとして提供されます。スタンドアロンOracleThread()のデフォルトはTrueです。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • memory_extraction_custom_instructions str | None–

    このスレッドの自動メモリー抽出システムプロンプトに追加されるオプションのカスタム命令。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • memory_extraction_inherit_message_metadata bool | Sequence[str]–

    自動的に抽出されたメモリーがソース・メッセージからメタデータを継承するかどうか。Trueを渡してすべてのメッセージ・メタデータを継承するか、それらのキーのみを継承する最上位メッセージ・メタデータ・キーの文字列以外の順序を使用するか、Falseを渡して継承を無効にします。デフォルトはTrueです。1つの抽出パスで複数のソース・メッセージを使用する場合、選択したメタデータはそれらのメッセージ間で一致する必要があります。

    情報:バージョン26.6.0以降非推奨: このパラメータは26.6.0で非推奨となり、27.1で削除されます。かわりにmemory_extraction_configを使用してください。

  • クライアント OracleAgentMemory | None

例

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

メソッド add_memory

手動メモリー・エントリを追加し、索引付けします。

• パラメータ:
  • content str– メモリーとして格納するテキスト・コンテンツ。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker– 格納するメモリーカテゴリ。サポートされている値は、"memory"、"fact"、"guideline"および"preference"です。省略すると、コンテンツは一般的な"memory"として格納されます。
  • user_id str– オプションのユーザー識別子のオーバーライド。
  • agent_id str– オプションのエージェント識別子のオーバーライド。
  • thread_id str– オプションのスレッド識別子のオーバーライド。
  • memory_id str– このメモリー行の呼び出し元提供の安定した識別子(オプション)。
  • metadata dict[str, Any] | None– 格納されているメモリーで保持するオプションのメタデータ。
  • timestamp str | None– このメモリー用に保存するオプションのタイムスタンプ。これは、メモリーが作成された時間を表します。省略またはNoneの場合、ストアは現在の時間を使用します。ttl_anchorがTimeToLiveAnchor.TIMESTAMPの場合は、具体的なISO-8601タイムスタンプ値を指定します。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • ttl_days int | None– オプションの稼働時間(日数)。スキーマ・デフォルトの存続時間を使用するには、この引数を省略します。Noneを渡して、保存構成の設定時にMemoryRetentionConfig.max_ttl_daysを使用するか、有効期限が切れないメモリーを格納します。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。
  • ttl_anchor TimeToLiveAnchor– オプションの稼働時間アンカー。データベース作成時間にはTimeToLiveAnchor.CREATED_ATを、メモリー・タイムスタンプにはTimeToLiveAnchor.TIMESTAMPを使用します。Timestamp-anchored有効期限には、このメモリーの具体的なISO-8601タイムスタンプが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメモリー・レコードの識別子。
• 戻り型: str

例

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

method add_memory_async (非同期)

メモリーを非同期的に追加します。

• パラメータ:
  • content str– 格納するメモリー・コンテンツ。
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker– 格納するメモリーカテゴリ。サポートされている値は、"memory"、"fact"、"guideline"および"preference"です。省略すると、コンテンツは一般的な"memory"として格納されます。
  • user_id str– オプションのユーザースコープオーバーライド。
  • agent_id str– オプションのエージェントスコープオーバーライド。
  • thread_id str– オプションのスレッドスコープオーバーライド。
  • memory_id str– オプションのコール元提供のメモリー識別子。省略すると、ストアはIDを生成します。
  • metadata dict[str, Any] | None– 格納されているメモリーで保持するオプションのメタデータ。
  • timestamp str | None– このメモリー用に保存するオプションのタイムスタンプ。これは、メモリーが作成された時間を表します。省略またはNoneの場合、ストアは現在の時間を使用します。
  • ttl_days int | None– オプションの稼働時間(日数)。この引数を省略して、スキーマのデフォルトの存続期間を使用するか、期限切れにならないメモリーにNoneを渡します。
  • ttl_anchor TimeToLiveAnchor– オプションの稼働時間アンカー。TimeToLiveAnchor.CREATED_ATまたはTimeToLiveAnchor.TIMESTAMPを使用します。
  • **store_kwargs (Any)– バッキングストアに転送される実装固有の書き込みオプション。
• 戻り型: str

メソッド add_messages

スレッドにメッセージを追加し、索引付けします。

バックグラウンド抽出モードでは、このメソッドはRAWメッセージの挿入後に戻り、バックグラウンドでのバックグラウンド抽出が試行されます。

• パラメータ:
  • messages list[Message | MessageT]– 追加するメッセージのリスト。メッセージは、roleおよびcontent (およびオプションのid)を使用したMessageオブジェクトまたはディクショナリです。
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]– 永続化するオプションの共有メタデータまたはメッセージごとのメタデータ。省略すると、各メッセージに埋め込まれたメタデータが使用されます。
  • ttl_days int | None | list[int | None]– 追加メッセージの存続期間(日数)。スキーマ・デフォルトの存続時間を使用するには、この引数を省略します。Noneを渡して、保存構成が設定されている場合にMemoryRetentionConfig.max_ttl_daysを使用するか、そうでない場合は期限切れでないメッセージを作成します。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。スカラー値は全バッチに適用されます。
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]– オプションの稼働時間アンカー。データベース作成時間にはTimeToLiveAnchor.CREATED_AT、メッセージ・タイムスタンプごとにTimeToLiveAnchor.TIMESTAMPを使用します。Timestamp-anchored期限切れには、影響を受ける各メッセージに対して具体的なISO-8601タイムスタンプが必要です。省略すると、メッセージはTimeToLiveAnchor.CREATED_ATを基準にして期限切れになります。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメッセージ・レコードの識別子。バックグラウンド抽出モードでは、これらの識別子が返されると、自動抽出作業がまだ実行されている可能性があります。
• 戻り型: list[str]

ノート:

MemoryExtractionMode.BACKGROUNDでは、抽出されたメモリーが格納される前にRAWメッセージが保持されます。バックグラウンド抽出がキューに入らない場合、または構成されたキュー容量の待機がタイムアウトに達した場合、挿入されたRAWメッセージは格納されたままになり、抽出されたメモリーなしでコールが続行されるか、background_extraction_queue_full_behaviorに応じてTimeoutErrorが呼び出されます。

例

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

method add_messages_async (非同期)

スレッドにメッセージを非同期に追加し、インデックスを作成します。

バックグラウンド抽出モードでは、このメソッドはRAWメッセージの挿入後に戻り、バックグラウンドでのバックグラウンド抽出が試行されます。

MemoryExtractionMode.BACKGROUNDでは、抽出されたメモリーが格納される前にRAWメッセージが保持されます。バックグラウンド抽出がキューに入らない場合、または構成されたキュー容量の待機がタイムアウトに達した場合、挿入されたRAWメッセージは格納されたままになり、抽出されたメモリーなしでコールが続行されるか、background_extraction_queue_full_behaviorに応じてTimeoutErrorが呼び出されます。

• パラメータ:
  • メッセージ list[Message | MessageT]
  • メタデータ dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• 戻り型: list[str]

メソッド delete_memory

メモリーに似たレコード(メモリー、ファクト、プリファレンス、ガイドラインなど)を、この正確なスレッドから識別子によって削除します。

• パラメータ: memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが削除されます。
• 戻り値:削除されたレコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int

例

thread.delete_memory("456")
0

メソッド delete_message

識別子によって、この正確なスレッドからメッセージ・レコードを削除します。

• パラメータ: message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが削除されます。
• 戻り値:削除されたメッセージ・レコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int

ノート:

メッセージを削除すると、RAWメッセージ・レコードのみが削除されます。導出された記憶は、どの抽出された記憶がどのメッセージから得られたかをまだ追跡していないため、削除されません。したがって、これらの記憶は検索可能なままになるか、コンテキスト・カードの出力に影響する可能性があります。OracleAgentMemory.delete_thread()を使用して、スレッドを関連するメッセージおよびメモリーとともに削除します。

例

thread.delete_message("123")
0

メソッド get_context_card

スレッドのコンテキスト・カード・オブジェクトを返します。

LLMがバックアップした実装でリモート・ネットワークI/Oを実行できる場合は、get_context_card_asyncを優先します。

• パラメータ:
  • fallback_message_count int– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。省略すると、これは5に解決されます。
  • max_relevant_results int– 含める取得された永続レコードの最大数。省略すると、min_relevant_results_by_typeが指定されないかぎり、これは5に解決されます。この場合、5の大きい方と、リクエストされたタイプごとの最小値の合計に解決されます。
  • max_recent_messages int–verbatimを埋め込む後続のrawメッセージの最大数。省略すると、これは5に解決されます。
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker– コンテキストカードに含まれる関連するメモリーに似たレコードについて、タイプごとの最小値(オプション)。リクエストされたタイプが最初に検索され、残りのmax_relevant_resultsスロットは、サポートされているすべてのメモリーに似たレコード・タイプから入力されます。サポートされているキーは、"memory"、"fact"、"guideline"および"preference"です。
  • **kwargs (Any)– 将来のコンテキストカードオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:最新のメッセージに基づくスレッド・コンテキスト・サマリーを含むコンテキスト・カード・オブジェクト。OracleContextCard.contentを使用して、レンダリングされたXMLのようなテキストにアクセスします。
• 戻りタイプ: OracleContextCard

ノート:

これは、スレッドのデフォルトの検索スコープをexact_thread_match=Falseとともに使用するため、同じユーザー/エージェントの他のスレッドからの関連メモリーが含まれる場合があります。

例

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

method get_context_card_async (非同期)

スレッドのコンテキスト・カード・オブジェクトを非同期で返します。

• パラメータ:
  • fallback_message_count int– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。省略すると、これは5に解決されます。
  • max_relevant_results int– 含める取得された永続レコードの最大数。省略すると、min_relevant_results_by_typeが指定されないかぎり、これは5に解決されます。この場合、5の大きい方と、リクエストされたタイプごとの最小値の合計に解決されます。
  • max_recent_messages int–verbatimを埋め込む後続のrawメッセージの最大数。省略すると、これは5に解決されます。
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker– コンテキストカードに含まれる関連するメモリーに似たレコードについて、タイプごとの最小値(オプション)。リクエストされたタイプが最初に検索され、残りのmax_relevant_resultsスロットは、サポートされているすべてのメモリーに似たレコード・タイプから入力されます。サポートされているキーは、"memory"、"fact"、"guideline"および"preference"です。
  • **kwargs (Any)– 将来のコンテキストカードオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:スレッドのコンテキスト・カード・オブジェクト。
• 戻りタイプ: OracleContextCard

例

card = await thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
)
len(card.relevant_results or []) <= 5
True

メソッド get_messages

このスレッドの格納されたメッセージを返します。

• パラメータ:
  • start int | None– 開始インデックス(0ベース)。endとともに省略すると、最新の境界ウィンドウが返されます。
  • end int | None– 終了インデックス(排他)。省略すると、最新のメッセージのバインドされたウィンドウが返されます。Noneまたは-1を渡して、start以降のすべてのメッセージを明示的にリクエストします。
• 戻り値:時系列順のメッセージ。
• 戻り型: list[Message]

例

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

method get_messages_async (非同期)

rawスレッドメッセージを非同期に返します。

• パラメータ:
  • start int | None– オプションの開始インデックス。
  • end int | None– オプションの終了インデックス。
• 戻り値: RAWメッセージ・オブジェクト。
• 戻り型: list[Message]

メソッド get_summary

スレッドのベスト・エフォート・サマリーを返します。

LLMがバックアップした実装でリモート・ネットワークI/Oを実行できる場合は、get_summary_asyncを優先します。

• パラメータ:
  • except_last int– サマリーから除外する最新のメッセージの数。
  • token_budget int– ソフトトークン予算。省略すると、境界のデフォルトが適用されます。正の値は、書式設定されたサマリーが_estimate_tokens()で推定される予算を超えた場合にのみ切り捨てられます。その後、返されたテキストはint(token_budget * 3.5)文字に制限されます。正以外の値は、出力境界を無効にします。
  • **kwargs (任意)– 将来のサマリーオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:合成スレッド・サマリー・テキストを含むサマリー・オブジェクト。
• 戻りタイプ: OracleSummary

例

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
bool(summary.content)
True

method get_summary_async (非同期)

スレッドのベスト・エフォート・サマリーを非同期で返します。

• パラメータ:
  • except_last int– サマリーから除外する最新のメッセージの数。
  • token_budget int– ソフトトークン予算。省略すると、境界のデフォルトが適用されます。正の値は、書式設定されたサマリーが_estimate_tokens()で推定される予算を超えた場合にのみ切り捨てられます。その後、返されたテキストはint(token_budget * 3.5)文字に制限されます。正以外の値は、出力境界を無効にします。
  • **kwargs (任意)– 将来のサマリーオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:合成スレッド・サマリー・テキストを含むサマリー・オブジェクト。
• 戻りタイプ: OracleSummary

メソッド search

クエリーに関連するレコードを同期的に検索します。

• パラメータ:
  • query str– 自然言語の問合せ文字列。
  • user_id str | None– オプションのユーザースコープオーバーライド。省略された値は、スレッドのデフォルトのユーザー・スコープを継承します。
  • agent_id str | None– オプションのエージェントスコープオーバーライド。省略された値は、スレッドのデフォルトのエージェント・スコープを継承します。
  • thread_id str | None– オプションのスレッドスコープオーバーライド。省略された値は、スレッドの現在のスレッド識別子を継承します。
  • exact_user_match bool– ユーザーの一致を厳密にするかどうか。
  • exact_agent_match bool– エージェントの一致を厳密にするかどうか。
  • exact_thread_match bool– スレッドの照合を厳密にするかどうか。
  • max_results int– 返す結果の最大数(オプション)。指定する場合は、1以上である必要があります。この引数を省略すると、デフォルト値の10が使用されます。期限切れでない一致レコードが存在する場合、コールはmax_resultsより少ない値を返す可能性があります。
  • record_types list[str]– 含めるレコード・タイプのオプションのリスト("memory"や"message"など)。

  • metadata_filter dict[str, Any] | None–

    スコープおよびレコード・タイプのフィルタリングの後に追加フィルタとして使用されるオプションのメタデータ・フィルタ・マッピング。metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリでないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは、格納されたレコード・メタデータに存在する必要があります。ネストされたディクショナリは、ネストされたメタデータ・オブジェクトを再帰的に一致させます。スカラー値とリスト値は完全に一致する必要があります。リストの順序と長さも一致する必要があります。メタデータ・フィルタリングなしで検索するには、この引数を省略するか、Noneを渡します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "chat"}、ネストしたフィールドの場合はmetadata_filter={"travel": {"need": "transit"}}、完全リスト一致の場合はmetadata_filter={"tags": ["trip", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    配列メンバーシップをテストするには、フィールド・レベルの演算子ディクショナリを使用します。"$array_contains"は、1つの値またはリスト内のすべての値と一致します。"$array_contains_any"は、リスト内の少なくとも1つの値と一致します。"$not"は、演算子ディクショナリまたはRAW完全一致値を含む、同じフィールド内の別のフィールド・レベル式を否定します。否定された式は、欠落しているフィールドを含め、正の式が失敗すると一致します。否定された配列メンバーシップは、非配列フィールドにも一致します。

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope– オプションの事前構築済み検索範囲。scopeまたは明示的な識別子と完全一致引数のいずれか(両方ではなく)を指定します。
• 戻り値:検索結果は、関連性の低下順に並べられます。
• 戻りタイプ: list[SearchResult]
• Raises: ValueError– scopeが明示的な識別子または完全一致引数と組み合されている場合、max_resultsが1より小さい場合、またはmetadata_filterがディクショナリでもNoneでもない場合。

ノート:

省略されたスコープ・フィールドは、このスレッドのデフォルトの検索スコープ(正確なユーザーおよびエージェントの一致に加えて、このスレッドの現在のuser_id、agent_idおよびthread_id)を継承します。デフォルトのスレッド検索は意図的にexact_thread_match=Falseを残すため、同じユーザー/エージェントの他のスレッドから関連レコードを返す場合があります。exact_thread_match=Trueを渡して、結果を現在のスレッドに制限します。明示的なNoneスコープ値は、解決された完全一致ルールに従います。exact_*_match=Falseはそのディメンションを制約なしのままにし、exact_*_match=Trueは格納されたNone値にのみ一致します。

明示的なmax_results値は、少なくとも1である必要があります。引数を省略すると、デフォルト値の10が使用されます。これは上限です。フィルタが制限しすぎる場合、一致するレコードの数が少ない場合、または実装固有の検索動作のため、コールはmax_resultsの結果より少ない場合があります。

method search_async (非同期)

クエリーに関連するレコードを非同期で検索します。

• パラメータ:
  • query str– 自然言語の問合せ文字列。
  • user_id str | None– オプションのユーザースコープオーバーライド。省略された値は、スレッドのデフォルトのユーザー・スコープを継承します。
  • agent_id str | None– オプションのエージェントスコープオーバーライド。省略された値は、スレッドのデフォルトのエージェント・スコープを継承します。
  • thread_id str | None– オプションのスレッドスコープオーバーライド。省略された値は、スレッドの現在のスレッド識別子を継承します。
  • exact_user_match bool– ユーザーの一致を厳密にするかどうか。
  • exact_agent_match bool– エージェントの一致を厳密にするかどうか。
  • exact_thread_match bool– スレッドの照合を厳密にするかどうか。
  • max_results int– 返す結果の最大数(オプション)。指定する場合は、1以上である必要があります。この引数を省略すると、デフォルト値の10が使用されます。
  • record_types list[str]– 含めるレコード・タイプのオプションのリスト("memory"や"message"など)。

  • metadata_filter dict[str, Any] | None–

    スコープおよびレコード・タイプのフィルタリングの後に追加フィルタとして使用されるオプションのメタデータ・フィルタ・マッピング。metadata_filterのエントリはANDセマンティクスと結合されます。値がフィールド・レベルの演算子ディクショナリでないエントリは、完全一致セマンティクスを使用します。つまり、リクエストされたキーは、格納されたレコード・メタデータに存在する必要があります。ネストされたディクショナリは、ネストされたメタデータ・オブジェクトを再帰的に一致させます。スカラー値とリスト値は完全に一致する必要があります。リストの順序と長さも一致する必要があります。メタデータ・フィルタリングなしで検索するには、この引数を省略するか、Noneを渡します。例として、スカラー・フィールドの場合はmetadata_filter={"source": "chat"}、ネストしたフィールドの場合はmetadata_filter={"travel": {"need": "transit"}}、完全リスト一致の場合はmetadata_filter={"tags": ["trip", "urgent"]}があります。条件を結合して、これらすべてを要求します。

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    配列メンバーシップをテストするには、フィールド・レベルの演算子ディクショナリを使用します。"$array_contains"は、1つの値またはリスト内のすべての値と一致します。"$array_contains_any"は、リスト内の少なくとも1つの値と一致します。"$not"は、演算子ディクショナリまたはRAW完全一致値を含む、同じフィールド内の別のフィールド・レベル式を否定します。否定された式は、欠落しているフィールドを含め、正の式が失敗すると一致します。否定された配列メンバーシップは、非配列フィールドにも一致します。

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • scope SearchScope– オプションの事前構築済み検索範囲。scopeまたは明示的な識別子と完全一致引数のいずれか(両方ではなく)を指定します。
• 戻り値:検索結果は、関連性の低下順に並べられます。
• 戻りタイプ: list[SearchResult]
• Raises: ValueError– scopeが明示的な識別子または完全一致引数と組み合されている場合、max_resultsが1より小さい場合、またはmetadata_filterがディクショナリでもNoneでもない場合。

ノート:

省略されたスコープ・フィールドは、このスレッドのデフォルトの検索スコープ(正確なユーザーおよびエージェントの一致に加えて、このスレッドの現在のuser_id、agent_idおよびthread_id)を継承します。デフォルトのスレッド検索は意図的にexact_thread_match=Falseを残すため、同じユーザー/エージェントの他のスレッドから関連レコードを返す場合があります。exact_thread_match=Trueを渡して、結果を現在のスレッドに制限します。明示的なNoneスコープ値は、解決された完全一致ルールに従います。exact_*_match=Falseはそのディメンションを制約なしのままにし、exact_*_match=Trueは格納されたNone値にのみ一致します。

明示的なmax_results値は、少なくとも1である必要があります。引数を省略すると、デフォルト値の10が使用されます。これは上限です。フィルタが制限しすぎる場合、一致するレコードの数が少ない場合、または実装固有の検索動作のため、コールはmax_resultsの結果より少ない場合があります。

メソッド update_memory

この正確なスレッドが所有するメモリーに似たレコードを更新します。

• パラメータ:
  • memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが更新されます。
  • content str– オプションの置換コンテンツ。格納されているコンテンツを置き換えるための文字列を指定します。省略すると、格納されたコンテンツは保持されます。Noneを渡すことはサポートされていません。contentを省略して現在の値を保持するか、delete_memory()を使用してレコードを削除します。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。省略すると、格納されたメタデータは保持されます。指定すると、格納されたメタデータ・オブジェクトが置き換えられます。このAPIはメタデータをディープ・マージしません。
  • timestamp str | None– このメモリー用のオプションの新しいタイムスタンプ。これは、メモリーが作成された時間を表します。省略すると、格納されているタイムスタンプが保持されます。Noneを渡して、保存されたタイムスタンプをクリアし、ストアでレコードが作成された時刻を使用します。ttl_anchorがTimeToLiveAnchor.TIMESTAMPの場合、置換タイムスタンプはISO-8601文字列である必要があります。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。ttl_anchorが指定されていないかぎり、現在の有効期限を変更しない場合は、この引数を省略します。Noneを渡して、保存構成が1つ設定されているときにMemoryRetentionConfig.max_ttl_daysを使用するか、そうでない場合は有効期限をクリアします。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。失効したメモリーはこのスレッドAPIで使用できず、リフレッシュできません。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。メモリー作成時間にはTimeToLiveAnchor.CREATED_AT、同じ更新で指定された置換timestampにはTimeToLiveAnchor.TIMESTAMP、timestampを省略した場合は格納されたイベント・タイムスタンプを使用します。ttl_daysを指定せずにttl_anchorを指定すると、スキーマのデフォルトの存続期間が使用されます。リフレッシュ中にttl_anchorを省略すると、スレッドはTimeToLiveAnchor.CREATED_ATを使用します。タイムスタンプ・アンカー・リフレッシュでは、同じコールの置換ISO-8601タイムスタンプ、またはその形式の既存の格納済イベント・タイムスタンプのいずれかが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメモリーに似たレコードの識別子。
• 戻り型: str

method update_memory_async (非同期)

メモリーに類似したレコードを非同期的に更新します。

• パラメータ:
  • memory_id str– 更新するメモリーに似たレコードの識別子。
  • content str– オプションの置換コンテンツ。格納されているコンテンツを置換する文字列を指定します。省略すると、格納されたコンテンツは保持されます。Noneを渡すことはサポートされていません。contentを省略して現在の値を保持するか、delete_memory()を使用してレコードを削除します。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。省略すると、格納されたメタデータは保持されます。指定すると、格納されたメタデータ・オブジェクトが置き換えられます。このAPIはメタデータをディープ・マージしません。
  • timestamp str | None– このメモリー用のオプションの新しいタイムスタンプ。これは、メモリーが作成された時間を表します。省略すると、格納されているタイムスタンプが保持されます。Noneを渡して、保存されたタイムスタンプをクリアし、ストアでレコードが作成された時刻を使用します。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。現在の有効期限タイムスタンプを保持するには、ttl_anchorとともにこの引数を省略します。Noneを渡して有効期限をクリアします。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。ttl_daysを指定せずにttl_anchorを指定すると、スキーマのデフォルトの存続期間が使用されます。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメモリーに似たレコードの識別子。
• 戻り型: str

例

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(thread.update_memory_async, memory_id, content="Updated memory")
) == memory_id
True

メソッド update_message

この正確なスレッドが所有するRAWメッセージ・レコードを更新します。

• パラメータ:
  • message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが更新されます。
  • content str– オプションの置換メッセージ・コンテンツ。格納されているコンテンツを置き換えるための文字列を指定します。省略すると、格納されたコンテンツは保持されます。Noneの受渡しはサポートされていません。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。省略すると、格納されたメタデータは保持されます。指定すると、格納されたメタデータ・オブジェクトが置き換えられます。このAPIはメタデータをディープ・マージしません。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。ttl_anchorが指定されていないかぎり、現在の有効期限を変更しない場合は、この引数を省略します。Noneを渡して、保存構成が1つ設定されているときにMemoryRetentionConfig.max_ttl_daysを使用するか、そうでない場合は有効期限をクリアします。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。期限切れのメッセージは、このスレッドAPIでは使用できず、リフレッシュできません。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。メッセージ作成時間にはTimeToLiveAnchor.CREATED_ATを、格納されたイベント・タイムスタンプにはTimeToLiveAnchor.TIMESTAMPを使用します。ttl_daysを指定せずにttl_anchorを指定すると、スキーマのデフォルトの存続期間が使用されます。リフレッシュ中にttl_anchorを省略すると、スレッドはTimeToLiveAnchor.CREATED_ATを使用します。Timestamp-anchoredリフレッシュには、格納されている既存のISO-8601メッセージ・タイムスタンプが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメッセージ・レコードの識別子。
• 戻り型: str

ノート:

省略されたフィールドは、格納されたレコードから保持されます。格納されたロールとタイムスタンプは変更されません。コンテンツを編集するとRAWメッセージ履歴が更新され、自動抽出が有効な場合、SDKが編集されたメッセージおよび以前の履歴からメモリーを再抽出する可能性があります。INLINEモードでは、このメソッドが返される前に抽出が完了します。BACKGROUNDモードでは、このメソッドはRAWメッセージ更新が成功し、バックグラウンド抽出が試行された後に戻ります。このフォローアップ作業は、後のadd_messages()コールで使用される通常の抽出頻度には影響しません。既存の抽出済メモリーは、編集済コンテンツから新しく抽出されたメモリーを追加できる間、そのまま残ります。RAWメッセージ更新および後で抽出されたメモリー書込みは原子的に発生しないため、バックグラウンド処理がキューに入らない場合、構成されたキュー容量待機がタイムアウトに達した場合、または後で抽出処理が失敗した場合でも、抽出されたメモリーは以前のメッセージ内容を反映できます。また、既存の抽出済メモリーは、ソース・メッセージのTTLが変更されたときに元の有効期限を保持することに注意してください。

例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

method update_message_async (非同期)

この正確なスレッドが所有するRAWメッセージ・レコードを非同期的に更新します。

• パラメータ:
  • message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが更新されます。
  • content str– オプションの置換メッセージ・コンテンツ。格納されているコンテンツを置き換えるための文字列を指定します。省略すると、格納されたコンテンツは保持されます。Noneの受渡しはサポートされていません。
  • metadata dict[str, Any] | None– オプションの置換メタデータマッピング。省略すると、格納されたメタデータは保持されます。指定すると、格納されたメタデータ・オブジェクトが置き換えられます。このAPIはメタデータをディープ・マージしません。
  • ttl_days int | None– オプションの有効期限のリフレッシュ(日数)。ttl_anchorが指定されていないかぎり、現在の有効期限を変更しない場合は、この引数を省略します。Noneを渡して、保存構成が1つ設定されているときにMemoryRetentionConfig.max_ttl_daysを使用するか、そうでない場合は有効期限をクリアします。MemoryRetentionConfig.max_ttl_daysを超える値は、警告付きでその最大値に固定されます。期限切れのメッセージは、このスレッドAPIでは使用できず、リフレッシュできません。
  • ttl_anchor TimeToLiveAnchor– 有効期限リフレッシュのオプションの存続時間アンカー。メッセージ作成時間にはTimeToLiveAnchor.CREATED_ATを、格納されたイベント・タイムスタンプにはTimeToLiveAnchor.TIMESTAMPを使用します。ttl_daysを指定せずにttl_anchorを指定すると、スキーマのデフォルトの存続期間が使用されます。Timestamp-anchoredリフレッシュには、格納されている既存のISO-8601メッセージ・タイムスタンプが必要です。タイムゾーンのないISO-8601タイムスタンプはUTCとして扱われます。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメッセージ・レコードの識別子。
• 戻り型: str

ノート:

省略されたフィールドは、格納されたレコードから保持されます。格納されたロールとタイムスタンプは変更されません。コンテンツを編集するとRAWメッセージ履歴が更新され、自動抽出が有効な場合、SDKが編集されたメッセージおよび以前の履歴からメモリーを再抽出する可能性があります。INLINEモードでは、このメソッドが返される前に抽出が完了します。BACKGROUNDモードでは、このメソッドはRAWメッセージ更新が成功し、バックグラウンド抽出が試行された後に戻ります。このフォローアップ作業は、後のadd_messages()コールで使用される通常の抽出頻度には影響しません。既存の抽出済メモリーは、編集済コンテンツから新しく抽出されたメモリーを追加できる間、そのまま残ります。RAWメッセージ更新および後で抽出されたメモリー書込みは原子的に発生しないため、バックグラウンド処理がキューに入らない場合、構成されたキュー容量待機がタイムアウトに達した場合、または後で抽出処理が失敗した場合でも、抽出されたメモリーは以前のメッセージ内容を反映できます。また、既存の抽出済メモリーは、ソース・メッセージのTTLが変更されたときに元の有効期限を保持することに注意してください。

例

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
run_async_in_sync(
    partial(thread.update_message_async, message_id, content="Edited message")
) == message_id
True

メソッド wait_for_memory_extraction

このスレッドの以前のバックグラウンドメモリー抽出を待ちます。

このメソッドは、同じエージェント・メモリー・コンポーネントを介して、以前のadd_messages()、add_messages_async()、update_message()またはupdate_message_async()コールによって開始されたバックグラウンド抽出を待機します。これらのコールのいずれかがすでに終了している場合、このメソッドには、待機前に開始する抽出が含まれます。

このメソッドは、この待機の開始後、別のエージェント・メモリー・コンポーネントによって開始された抽出、または別のプロセスで実行されている抽出の開始を待機しません。この待機の終了時に抽出の失敗がカウントされます。

• パラメータ: timeout float | None– 待機する最大秒数(オプション)。デフォルトは300です。Noneを渡して、このスレッドの保留中の抽出が終了するまで待機します。
• Raises: TimeoutError– 以前のバックグラウンド抽出が終了する前にタイムアウトが期限切れになると発生します。
• 戻り型:なし

例

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (非同期)

以前のバックグラウンド・メモリー抽出を非同期に待機します。

このメソッドは、wait_for_memory_extraction()と同じ動作に従います。

• パラメータ: timeout float | None– 待機する最大秒数(オプション)。デフォルトは300です。Noneを渡して無期限に待機します。
• Raises: TimeoutError– 以前のバックグラウンド抽出が終了する前にタイムアウトが期限切れになると発生します。
• 戻り型:なし

例

await thread.wait_for_memory_extraction_async(timeout=10)

ノート: delete_message()は、RAWメッセージ行のみを削除します。導出された記憶は引き続き検索可能であるか、コンテキスト・カードに表示されます。OracleAgentMemory.delete_thread()を使用して、スレッドを関連するメッセージおよびメモリーとともに削除します。クライアント・レベルのスレッド削除は、そのスレッドですでに認識されている、以前に受け入れられたバックグラウンド抽出を待機しますが、削除の進行中は、同じスレッド上の他の操作に対するグローバルな同時実行性の障壁ではありません。

メッセージ

クラス oracleagentmemory.apis.thread.Message

ベース: object

• パラメータ:
  • role str
  • コンテンツ str
  • タイムスタンプ str | None
  • メタデータ dict[str, Any] | None
  • id str | None

コンテキスト・カード

クラス oracleagentmemory.apis.contextcard.ContextCard

ベース: ABC

スレッドAPIによって返される抽象コンテキスト・カード・オブジェクト。

property content (抽象)

• 戻りタイプ: str
• 説明:レンダリングされたコンテキスト・カード・テキストを返します。

クラス oracleagentmemory.core.contextcard.OracleContextCard

ベース: ContextCard

Oracleスレッドによって返されたコンテキスト・カード。

• パラメータ:
  • summary str– カードに埋め込まれたサマリーテキスト。
  • topics Sequence[str] | None– スレッドに関連付けられたオプションの取得トピック。
  • relevant_results Sequence[SearchResult] | None– カードに含まれる、オプションで取得された永続レコード。
  • recent_messages Sequence[Message] | None– カードにレンダリングされる、オプションの最近のrawメッセージ。
  • message_format str– recent_messagesのレンダリング時に使用される内部テンプレート。

プロパティ content

• 戻りタイプ: str

• 説明:レンダリングされたコンテキスト・カード・テキストを返します。

• 戻り値:プロンプト・アセンブリに適したXML形式のレンダリング済コンテキスト・カード・テキスト。
• 戻り型: str

例

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

property formatted_content

• 戻りタイプ: str

• 説明:プロンプト作成フローで使用されるレンダリングされたコンテキスト・カード・テキストを返します。

• 戻り値: XMLに似たレンダリングされたコンテキスト・カード・テキスト。
• 戻り型: str

例

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

サマリー

クラス oracleagentmemory.apis.summary.Summary

ベース: ABC

スレッドAPIによって返される抽象スレッド・サマリー・オブジェクト。

property content (抽象)

• 戻りタイプ: str
• 説明:合成されたサマリー・テキストを返します。

クラス oracleagentmemory.core.summary.OracleSummary

ベース: Summary

Oracleスレッドによって返されるサマリー。

• パラメータ: content str– スレッド・トランスクリプトから合成されたサマリー・テキスト。

例

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

プロパティ content

• 戻りタイプ: str

• 説明:合成されたサマリー・テキストを返します。

• 戻り値:スレッドのサマリー・テキスト。
• 戻り型: str

例

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

property formatted_content

• 戻りタイプ: str

• 説明:プロンプト作成フローで使用されるレンダリングされたサマリー・テキストを返します。

• 戻り値:レンダリングされたサマリー・テキスト。
• 戻り型: str

例

OracleSummary(content="Thread recap").formatted_content
'Thread recap'