スレッド

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

Oracleスレッド

クラス oracleagentmemory.core.OracleThread

ベース: IThread

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

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

ノート

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

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

• パラメータ:
  • store OracleMemoryStore– 埋込みレコードの永続化に使用される共有ストア・バックエンド。
  • thread_id str– スレッド識別子。指定しない場合、UUIDが生成されます。
  • user_id str– スレッドに関連付けられたユーザー識別子。DB SchemaPolicy.NO_CHECKランタイム・ストアで省略すると、アクティブなエンドユーザー・セキュリティ・コンテキストのユーザー名が使用されます。それ以外の場合、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のデフォルトを使用し、コンテキスト・サマリーを有効のままにします。省略されたイメージ・コンテキストはDISABLEDです。
  • image_input_limit_config ImageInputLimitConfig– このスタンドアロンスレッドに対するオプションのrawイメージおよびLLMイメージ要求の制限。省略されたフィールドには、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–

    最新の有効なサマリーの後に自動的にリフレッシュするまでのメッセージ数。メモリー抽出が有効になっている場合、チェックは各抽出の期限後に行われるため、あとでリフレッシュが発生する可能性があります。0以下の値は、チェックごとにリフレッシュされます。デフォルトは-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を指定すると、OAMは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を使用してください。

  • search_config MemorySearchConfig– このスレッドのオプションの検索構成。省略すると、検索は固定されたtop-k検索構成を使用します。
  • クライアント OracleAgentMemory | None

例

from oracleagentmemory.core import MemoryExtractionConfig, OracleAgentMemory
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c4",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(enable_context_summary=True),
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

メソッド add_image

このスレッドに関連付けられた1つのイメージを保持します。

descriptionは、イメージの検索可能なテキストとして格納されます。省略またはNoneを指定すると、アタッチされたLLMによってキャプションが生成されます。省略されたスコープ値は、このスレッドの対応するユーザー、エージェント、およびスレッド識別子を継承します。

• パラメータ:
  • image bytes– 永続化するrawイメージバイト数。
  • description str | None– オプションの説明またはキャプション。省略してキャプションを生成します。
  • mime_type ImageMimeType– イメージの永続性およびキャプションの生成に使用されるオプションのMIMEタイプ。省略すると、SDKはイメージ・バイトからタイプを検出して検証します。サポートされている検出タイプは、PNG、JPEGおよびWEBPです。
  • image_id str– オプションの識別子。省略すると生成されます。
  • user_id str | None– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • agent_id str | None– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • thread_id str– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • metadata dict[str, Any] | None– イメージとともに格納されるオプションのメタデータ。
  • timestamp str | None– このイメージ用に保存するオプションのイベントタイムスタンプ。この引数を省略するか、Noneを渡してNULLイベント・タイムスタンプを格納します。イメージが読み取られると、その作成時間が有効なタイムスタンプとして返されます。
  • ttl_days int | None– オプションの有効期限設定。
  • ttl_anchor TimeToLiveAnchor– オプションの有効期限設定。
  • store_kwargs Any– 追加のストア固有オプション。
• 戻り値:永続イメージ識別子。
• 戻り型: str

method add_image_async (非同期)

このスレッドに関連付けられた1つのイメージを非同期に保持します。

descriptionは、イメージの検索可能なテキストとして格納されます。省略またはNoneを指定すると、アタッチされたLLMによってキャプションが生成されます。省略されたスコープ値は、このスレッドの対応するユーザー、エージェント、およびスレッド識別子を継承します。

• パラメータ:
  • image bytes– 永続化するrawイメージバイト数。
  • description str | None– オプションの説明またはキャプション。省略してキャプションを生成します。
  • mime_type ImageMimeType– イメージの永続性およびキャプションの生成に使用されるオプションのMIMEタイプ。省略すると、SDKはイメージ・バイトからタイプを検出して検証します。サポートされている検出タイプは、PNG、JPEGおよびWEBPです。
  • image_id str– オプションの識別子。省略すると生成されます。
  • user_id str | None– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • agent_id str | None– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • thread_id str– オプションのスコープアサーション。省略された値は、このスレッドのスコープを継承します。指定された値は完全に一致する必要があります。
  • metadata dict[str, Any] | None– イメージとともに格納されるオプションのメタデータ。
  • timestamp str | None– このイメージ用に保存するオプションのイベントタイムスタンプ。この引数を省略するか、Noneを渡してNULLイベント・タイムスタンプを格納します。イメージが読み取られると、その作成時間が有効なタイムスタンプとして返されます。
  • ttl_days int | None– オプションの有効期限設定。
  • ttl_anchor TimeToLiveAnchor– オプションの有効期限設定。
  • store_kwargs Any– 追加のストア固有オプション。
• 戻り値:永続イメージ識別子。
• 戻り型: str

メソッド 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を渡してNULLイベント・タイムスタンプを格納します。レコードが読み取られると、その作成時間が有効なタイムスタンプとして返されます。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として扱われます。
  • status RecordStatus– 初期ライフサイクル・ステータス。RecordStatus.VALIDを格納する場合は省略します。
  • autonomous_linking bool– スレッドのLLMを使用して、この新しいメモリーから関連する格納済みメモリーへのリンクを作成するかどうか。省略すると、LLMが存在する場合に有効になり、Falseを渡してスキップします。失敗すると、メモリーが格納されます。
  • memory_id_to_link str– 同時に、新しいメモリーからこの既存のスレッド所有メモリーへの有向リンクを作成します。省略されたユーザー、エージェントおよびスレッド・スコープは、そのターゲットから継承されます。明示的なリンクを作成しない場合は、両方を省略します。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker– 同時に、新しいメモリーからこの既存のスレッド所有メモリーへの有向リンクを作成します。省略されたユーザー、エージェントおよびスレッド・スコープは、そのターゲットから継承されます。明示的なリンクを作成しない場合は、両方を省略します。
  • link_id str– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • link_timestamp str | None– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • link_metadata dict[str, Any] | None– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • **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– このメモリー行の呼び出し元提供の安定した識別子(オプション)。
  • metadata dict[str, Any] | None– 格納されているメモリーで保持するオプションのメタデータ。
  • timestamp str | None– このメモリー用に保存するオプションのイベントタイムスタンプ。この引数を省略するか、Noneを渡してNULLイベント・タイムスタンプを格納します。レコードが読み取られると、その作成時間が有効なタイムスタンプとして返されます。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として扱われます。
  • status RecordStatus– 初期ライフサイクル・ステータス。RecordStatus.VALIDを格納する場合は省略します。
  • autonomous_linking bool– スレッドのLLMを使用して、この新しいメモリーから関連する格納済みメモリーへのリンクを作成するかどうか。省略すると、LLMが存在する場合に有効になり、Falseを渡してスキップします。失敗すると、メモリーが格納されます。
  • memory_id_to_link str– 同時に、新しいメモリーからこの既存のスレッド所有メモリーへの有向リンクを作成します。省略されたユーザー、エージェントおよびスレッド・スコープは、そのターゲットから継承されます。明示的なリンクを作成しない場合は、両方を省略します。
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker– 同時に、新しいメモリーからこの既存のスレッド所有メモリーへの有向リンクを作成します。省略されたユーザー、エージェントおよびスレッド・スコープは、そのターゲットから継承されます。明示的なリンクを作成しない場合は、両方を省略します。
  • link_id str– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • link_timestamp str | None– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • link_metadata dict[str, Any] | None– 明示的リンクのオプションの識別子、タイムスタンプ、およびメタデータ。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメモリー・レコードの識別子。
• 戻り型: str

例

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

メソッド add_messages

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

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

RAWメッセージは、自動抽出の前にどちらのモードでも格納されます。後で抽出または導出メモリー・ストレージが失敗した場合、RAWメッセージは格納されたままになりますが、導出されたメモリーまたはサマリー更新が欠落する可能性があります。

• パラメータ:
  • messages Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]– 追加するメッセージのリスト。メッセージは、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メッセージの挿入後に戻り、バックグラウンドでのバックグラウンド抽出が試行されます。

RAWメッセージは、自動抽出の前にどちらのモードでも格納されます。後で抽出または導出メモリー・ストレージが失敗した場合、RAWメッセージは格納されたままになりますが、導出されたメモリーまたはサマリー更新が欠落する可能性があります。

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

• パラメータ:
  • メッセージ Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]
  • メタデータ 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_image

このスレッドが所有する画像を1つ削除します。

• パラメータ: image_id str– 削除するイメージの識別子。
• 戻り値:削除する場合は1、それ以外の場合はイメージが存在しないか、別のスレッドに属している場合は0。
• 戻り型: int
• Raises: ValueError– イメージがメッセージに添付されている場合。かわりに親メッセージを削除または更新してください。

method delete_image_async (非同期)

このスレッドが所有するイメージを非同期で削除します。

• パラメータ: image_id str– 削除するイメージの識別子。
• 戻り値:削除する場合は1、それ以外の場合はイメージが存在しないか、別のスレッドに属している場合は0。
• 戻り型: int
• Raises: ValueError– イメージがメッセージに添付されている場合。かわりに親メッセージを削除または更新してください。

メソッド delete_memory

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

• パラメータ: memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが削除されます。
• 戻り値:削除されたレコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int
• Raises: TimeoutError– 以前に受け入れたこのスレッドのバックグラウンド抽出が300秒以内に終了しない場合は、レコードを削除せずに呼び出されます。

ノート

レコードを削除する前に、このメソッドは、アタッチされたエージェント・メモリー・コンポーネントを介して、このスレッドに対して受け入れられた以前のバックグラウンド抽出を待機します。待機の開始後、または別のコンポーネントまたはプロセスによって開始された作業が受け入れられるまで待機しません。

例

thread.delete_memory("456")
0

method delete_memory_async (非同期)

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

• パラメータ: memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが削除されます。
• 戻り値:削除されたレコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int
• Raises: TimeoutError– 以前に受け入れたこのスレッドのバックグラウンド抽出が300秒以内に終了しない場合は、レコードを削除せずに呼び出されます。

ノート

このメソッドは、delete_memory()で説明されているバックグラウンド抽出待機および同時実行性の動作に従います。

例

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

メソッド delete_message

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

• パラメータ: message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが削除されます。
• 戻り値:削除されたメッセージ・レコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int
• Raises: TimeoutError– このスレッドに対して以前に受け入れたバックグラウンド抽出が300秒以内に終了しない場合は、メッセージを削除せずに呼び出されます。

ノート

メッセージを削除する前に、このメソッドは、アタッチされたエージェント・メモリー・コンポーネントを介して、このスレッドに対して受け入れられた以前のバックグラウンド抽出を待機します。待機の開始後、または別のコンポーネントまたはプロセスによって開始された作業が受け入れられるまで待機しません。

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

例

thread.delete_message("123")
0

method delete_message_async (非同期)

識別子別にこの正確なスレッドからメッセージ・レコードを非同期的に削除します。

• パラメータ: message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが削除されます。
• 戻り値:削除されたメッセージ・レコードの数(0または1)。識別子が存在しないか、別のスレッドに属している場合、0を返します。
• 戻り型: int
• Raises: TimeoutError– このスレッドに対して以前に受け入れたバックグラウンド抽出が300秒以内に終了しない場合は、メッセージを削除せずに呼び出されます。

ノート

このメソッドは、delete_message()で説明されているバックグラウンド抽出待機および同時実行性の動作に従います。

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

例

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

メソッド delete_record_link

IDまたは完全なエンドポイント・タプルによるスレッド所有リレーションの削除。

エンドポイント・タプル・セレクタでは、格納されたソースとターゲットの方向を使用する必要があります。

• パラメータ:
  • source_record_id str– エンドポイント・タプル・セレクタのソース識別子。
  • source_record_type str– エンドポイント・タプル・セレクタの論理ソース・レコード・タイプ。
  • target_record_id str– エンドポイントタプルセレクタのターゲット識別子。
  • target_record_type str– エンドポイント・タプル・セレクタの論理ターゲット・レコード・タイプ。
  • relation_type str– エンドポイント・タプル・セレクタのソースからターゲットへのラベル。
  • relation_id str– 直接選択するリレーション識別子。この引数を単独で指定してください。
• 戻り値:削除されたリレーションの数(0または1)。
• 戻り型: int

例

thread.delete_record_link(relation_id="relation-id")
1

method delete_record_link_async (非同期)

このスレッドが所有するリレーションを非同期に削除します。

• パラメータ:
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • relation_id str
• 戻り型: int

メソッド get_context_card

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

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

• パラメータ:
  • fallback_message_count int– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。省略すると、これは5に解決されます。

  • max_relevant_results int–

    コンテキスト・カードの<relevant_information>セクションに含める関連レコード(たとえば、ファクト/プリファレンス、メッセージなど)の最大数。

    • この値とmin_relevant_results_by_typeの両方を省略すると、max_relevant_resultsは5に解決されます。
    • min_relevant_results_by_typeが指定されている場合、max_relevant_resultsはmax(max_relevant_results, sum(min_relevant_results_by_type.values()))に解決されます。
  • token_budget int | None– コンテキストカード内のフォーマットされた関連結果の推定トークン数に対するオプションの強い制限。省略すると、スレッド検索構成が使用されます。正の値は完全な結果をランク順に保持し、累積見積は予算に適合します。最初の結果が収まらない場合、関連する結果は含まれません。正の値でない場合、上限は無効になります。
  • soft_token_budget int | None– フォーマットされた関連結果の推定トークン数に対するオプションのターゲット。省略すると、スレッド検索構成が使用されます。このターゲットに到達または超えた完全な結果が保持されます。非正の値は、このターゲットを無効にします。出力にも絶対制限が必要な場合は、token_budgetを大きい値に設定します。
  • max_recent_messages int– コンテキストカードの <recent_messages>セクションに含める最近の会話メッセージの最大数。省略すると、max_recent_messagesは0に解決されます。

  • except_last_messages int–

    生成されたサマリーおよびコンテキスト・カードに含まれる関連情報検索から除外する後続メッセージの数。これにより、LLMプロンプトで別々に提供されるメッセージがコンテキスト・カードで複製されるのを防ぎます。次のパターンのいずれかを使用します。

    • 外部RAWテール(プロンプト・キャッシュに推奨):

      get_context_card(except_last_messages=N, max_recent_messages=0)プロンプトには、コンテキスト・カードの後に最後のN RAWメッセージが続きます。

    • 自己完結型コンテキスト・カード:

      get_context_card(except_last_messages=N, max_recent_messages=N)コンテキスト・カードには、最後のNメッセージ自体が含まれます。

    ゼロ以外の場合、max_recent_messagesは0または同じ値である必要があります。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker– コンテキストカードに含まれる関連レコードについて、タイプごとのオプションの最小値。リクエストされたタイプが最初に検索され、残りのmax_relevant_resultsスロットは、サポートされているすべてのメモリーに似たレコード・タイプから入力されます。サポートされているキーは、"memory"、"fact"、"guideline"、"preference"および"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"},
        },
    }

  • include_invalid_results bool– 無効なライフサイクル・ステータスの関連レコードがコンテキスト・カードに含まれるかどうか。この引数を省略するか、Trueを渡して含めます。Falseを渡して除外します。
  • **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–

    コンテキスト・カードの<relevant_information>セクションに含める関連レコード(たとえば、ファクト/プリファレンス、メッセージなど)の最大数。

    • この値とmin_relevant_results_by_typeの両方を省略すると、max_relevant_resultsは5に解決されます。
    • min_relevant_results_by_typeが指定されている場合、max_relevant_resultsはmax(max_relevant_results, sum(min_relevant_results_by_type.values()))に解決されます。
  • token_budget int | None– コンテキストカード内のフォーマットされた関連結果の推定トークン数に対するオプションの強い制限。省略すると、スレッド検索構成が使用されます。正の値は完全な結果をランク順に保持し、累積見積は予算に適合します。最初の結果が収まらない場合、関連する結果は含まれません。正の値でない場合、上限は無効になります。
  • soft_token_budget int | None– フォーマットされた関連結果の推定トークン数に対するオプションのターゲット。省略すると、スレッド検索構成が使用されます。このターゲットに到達または超えた完全な結果が保持されます。非正の値は、このターゲットを無効にします。出力にも絶対制限が必要な場合は、token_budgetを大きい値に設定します。
  • max_recent_messages int– コンテキストカードの <recent_messages>セクションに含める最近の会話メッセージの最大数。省略すると、max_recent_messagesは0に解決されます。

  • except_last_messages int–

    生成されたサマリーおよびコンテキスト・カードに含まれる関連情報検索から除外する後続メッセージの数。これにより、LLMプロンプトで別々に提供されるメッセージがコンテキスト・カードで複製されるのを防ぎます。次のパターンのいずれかを使用します。

    • 外部RAWテール(プロンプト・キャッシュに推奨):

      get_context_card(except_last_messages=N, max_recent_messages=0)プロンプトには、コンテキスト・カードの後に最後のN RAWメッセージが続きます。

    • 自己完結型コンテキスト・カード:

      get_context_card(except_last_messages=N, max_recent_messages=N)コンテキスト・カードには、最後のNメッセージ自体が含まれます。

    ゼロ以外の場合、max_recent_messagesは0または同じ値である必要があります。

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker– コンテキストカードに含まれる関連レコードについて、タイプごとのオプションの最小値。リクエストされたタイプが最初に検索され、残りのmax_relevant_resultsスロットは、サポートされているすべてのメモリーに似たレコード・タイプから入力されます。サポートされているキーは、"memory"、"fact"、"guideline"、"preference"および"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"},
        },
    }

  • include_invalid_results bool– 無効なライフサイクル・ステータスの関連レコードがコンテキスト・カードに含まれるかどうか。この引数を省略するか、Trueを渡して含めます。Falseを渡して除外します。
  • **kwargs (Any)– 将来のコンテキストカードオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:スレッドのコンテキスト・カード・オブジェクト。
• 戻りタイプ: OracleContextCard

例

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

メソッド get_message

このスレッドが所有するメッセージを1つ返します。

イメージ・パーツは、デフォルトでその識別子と説明とともに返されます。included_image_idsを渡して、選択したイメージ・パートのバイトをロードします。関連のない識別子は無視されます。

• パラメータ:
  • message_id str– 取得するメッセージの識別子。メッセージはこのスレッドに属している必要があります。
  • included_image_ids list[str]– バイトをロードする必要がある添付されたイメージ識別子のオプションのリスト。この引数を省略するか、Noneを渡して、バイトをロードせずにイメージ・メタデータを返します。
• 戻り値:リクエストされたメッセージ(アタッチされたイメージ部分を含む)。
• 戻り型: Message
• Raises: KeyError– メッセージが存在しないか、別のスレッドに属している場合。

method get_message_async (非同期)

スレッド所有のメッセージを非同期で返します。

included_image_idsはオプションで、バイトをロードする必要があるアタッチされたイメージ・パートを選択します。省略するか、Noneはイメージ・メタデータのみを返します。

• パラメータ:
  • message_id str– 取得するメッセージの識別子。メッセージはこのスレッドに属している必要があります。
  • included_image_ids list[str]– ハイドレートする接続されたイメージ識別子のオプションのリスト。
• 戻り値:リクエストされたメッセージ(アタッチされたイメージ部分を含む)。
• 戻り型: Message
• Raises: KeyError– メッセージが存在しないか、別のスレッドに属している場合。

メソッド get_messages

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

• パラメータ:
  • start int | None– 開始インデックス(0ベース)。endとともに省略すると、最新の境界ウィンドウが返されます。
  • end int | None– 終了インデックス(排他)。省略すると、最新のメッセージのバインドされたウィンドウが返されます。Noneまたは-1を渡して、start以降のすべてのメッセージを明示的にリクエストします。
  • include_image_bytes bool– 返されたメッセージに添付されたイメージ部分のバイトをロードするかどうか。この引数を省略するか、Falseを渡して、BLOB値をロードせずにイメージ・メタデータを戻します。
• 戻り値:時系列順のメッセージ。
• 戻り型: 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 (非同期)

add_messagesで非同期的に追加された未処理のメッセージをスレッドから取得します。

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

例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

メソッド get_summary

スレッドのサマリーを返します。

全体スレッド・リクエストは、永続サマリーを再利用またはリフレッシュします。except_lastを使用したリクエストは、永続スレッド・サマリーを変更せずにその接頭辞を要約します。

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

• パラメータ:
  • except_last int– サマリーから除外する最新のメッセージの数。
  • token_budget int– ソフトトークン予算。省略すると、境界のデフォルトが適用されます。正の値は、書式設定された要約が予算を超えた場合にのみ切り捨てられます。正の値でない場合、予算ベースの切捨ては無効になります。トランスクリプト・フォールバックは4,000文字に制限されます。
  • **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を使用したリクエストは、永続スレッド・サマリーを変更せずにその接頭辞を要約します。

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

メソッド link_records

このスレッドが所有する2つのレコード間の有向リレーションを作成します。

現在、両方のエンドポイントはメモリーに似たレコード("memory"、"fact"、"guideline"または"preference")である必要があります。組込みのリレーション型は、"supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by")および"duplicates"です。"contradicts"と"duplicates"は、同じラベルを逆に使用します。

両方のエンドポイントは、この正確なスレッドに属している必要があります。1つのエンドポイント・ペアに対して格納できる方向は1つのみです。opposite_relation_typeは、ターゲットからソースへのトラバース時にリレーションに名前を付けます。たとえば、new "supersedes" oldはその方向でold "is_superseded_by" newになります。

• パラメータ:
  • source_record_id str– スレッド所有のソースレコードの識別子。
  • source_record_type str– ソース・レコードの論理型。
  • target_record_id str– スレッド所有のターゲットレコードの識別子。
  • target_record_type str– ターゲット・レコードの論理型。
  • relation_type str - ソースとターゲットの関係ラベル。
  • opposite_relation_type str– オプションの逆方向ラベル。組み込みメモリーリレーションタイプの場合、省略は定義済みの逆ラベルを使用します。カスタムリレーションタイプの場合、省略は両方向に同じラベルを使用します。
  • relation_id str– オプションの安定したリレーション識別子。これを省略して生成します。
  • timestamp str | None– リレーションに格納されるオプションのタイムスタンプ。
  • metadata dict[str, Any] | None– オプションのリレーション・メタデータ。
• 戻り値:作成されたリレーションの識別子。
• 戻り型: str

例

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

method link_records_async (非同期)

このスレッドが所有するレコード間のリレーションを非同期的に作成します。

現在、両方のエンドポイントはメモリーに似たレコード("memory"、"fact"、"guideline"または"preference")である必要があります。組込みのリレーション型は、"supersedes" ("is_superseded_by")、"contradicts"、"refines" ("is_refined_by")、"supports" ("is_supported_by")および"duplicates"です。"contradicts"と"duplicates"は、同じラベルを逆に使用します。

• パラメータ:
  • source_record_id str
  • source_record_type str
  • target_record_id str
  • target_record_type str
  • relation_type str
  • opposite_relation_type str
  • relation_id str
  • タイムスタンプ str | None
  • メタデータ dict[str, Any] | None
• 戻り型: str

メソッド list_images

このスレッドが所有するイメージ・レコードをリストします。

返されるレコードには、デフォルトでイメージ・メタデータが含まれます。RAWバイトは、include_bytes=Trueおよびimage_idが指定されている場合にのみロードされます。

• パラメータ:
  • image_id str– イメージのフィルタに使用されるオプションの識別子。省略すると、識別子フィルタは適用されません。
  • metadata_filter dict[str, Any] | None– イメージメタデータに適用されるオプションのフィルタ。
  • include_bytes bool–rawバイトをロードするかどうか。これにはimage_idが必要です。
  • limit int | None– オプションの最大レコード数。ストアのデフォルトの制限を無効にするには、Noneを渡します。
• 戻り値:ストア順序で一致するイメージ。
• 戻り型: list[ImageRecord]

method list_images_async (非同期)

このスレッドが所有するイメージ・レコードを非同期的にリストします。

返されるレコードには、デフォルトでイメージ・メタデータが含まれます。RAWバイトは、include_bytes=Trueおよびimage_idが指定されている場合にのみロードされます。このスレッドのスコープは自動的に適用されます。

• パラメータ:
  • image_id str– イメージのフィルタに使用されるオプションの識別子。省略すると、識別子フィルタは適用されません。
  • metadata_filter dict[str, Any] | None– イメージメタデータに適用されるオプションのフィルタ。
  • include_bytes bool–rawバイトをロードするかどうか。これにはimage_idが必要です。
  • limit int | None– オプションの最大レコード数。ストアのデフォルトの制限を無効にするには、Noneを渡します。
• 戻り値:ストア順序で一致するイメージ。
• 戻り型: list[ImageRecord]

メソッド 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より少ない値を返す可能性があります。
  • token_budget int– 最終的にフォーマットされた結果の推定トークン数に対するオプションの強い制限。省略すると、解決された検索構成が使用されます。正の値は完全な結果をランク順に保持し、累積見積は予算に適合します。最初の結果が収まらない場合、結果は返されません。正以外の値は、この出力境界を無効にします。
  • soft_token_budget int– 最終的な書式付き結果の推定トークン数に対するオプションのターゲット。省略すると、解決された検索構成が使用されます。このターゲットに到達または超えた完全な結果が保持されます。非正の値は、このターゲットを無効にします。出力にも絶対制限が必要な場合は、token_budgetを大きい値に設定します。
  • record_types list[str]– 含めるレコード・タイプのオプションのリスト("memory"、"message"、"image"など)。

  • 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"},
        },
    }

  • include_invalid_results bool– 結果に無効なステータスのレコードが含まれるかどうか。この引数を省略するか、Trueを渡して含めます。Falseを渡して除外します。
  • num_hops int– 各ダイレクトメモリー結果から従うメモリーリンクエッジの数。0から5までの値がサポートされています。直接の結果の場合のみ省略してください。ダイレクト・メッセージ、イメージおよびプロファイルの結果は保持されますが、グラフは展開されません。
  • max_linked_results int– 各直接結果にアタッチされたすべてのホップ間でリンクされたメモリーの最大数。デフォルトの100を省略し、0を渡してリンクされたコンテキストを返しません。
  • 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が使用されます。
  • token_budget int– 最終的にフォーマットされた結果の推定トークン数に対するオプションの強い制限。省略すると、解決された検索構成が使用されます。正の値は完全な結果をランク順に保持し、累積見積は予算に適合します。最初の結果が収まらない場合、結果は返されません。正以外の値は、この出力境界を無効にします。
  • soft_token_budget int– 最終的な書式付き結果の推定トークン数に対するオプションのターゲット。省略すると、解決された検索構成が使用されます。このターゲットに到達または超えた完全な結果が保持されます。非正の値は、このターゲットを無効にします。出力にも絶対制限が必要な場合は、token_budgetを大きい値に設定します。
  • record_types list[str]– 含めるレコード・タイプのオプションのリスト("memory"、"message"、"image"など)。

  • 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"},
        },
    }

  • include_invalid_results bool– 結果に無効なステータスのレコードが含まれるかどうか。この引数を省略するか、Trueを渡して含めます。Falseを渡して除外します。
  • num_hops int– 各ダイレクトメモリー結果から従うメモリーリンクエッジの数。0から5までの値がサポートされています。直接の結果の場合のみ省略してください。ダイレクト・メッセージ、イメージおよびプロファイルの結果は保持されますが、グラフは展開されません。
  • max_linked_results int– 各直接結果にアタッチされたすべてのホップ間でリンクされたメモリーの最大数。デフォルトの100を省略し、0を渡してリンクされたコンテキストを返しません。
  • 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_image

このスレッドが所有する1つのイメージを更新します。

既存のバイトを保持するには、imageを省略します。imageを指定する場合は、mime_typeを指定する必要があります。既存の説明を保持するには、descriptionを省略します。Noneを渡して、構成されたLLMで新しい説明を生成します。nullでない説明によって、その説明が直接置き換えられます。メッセージに添付されたイメージの有効期限は、update_message()を使用して変更する必要があります。

• 戻り値:更新されたイメージ識別子。
• 戻り型: str
• Raises: ValueError– メッセージに添付されたイメージに有効期限設定が指定されている場合。
• パラメータ:
  • image_id str
  • イメージ bytes
  • 説明 str | None
  • mime_type ImageMimeType
  • メタデータ dict[str, Any] | None
  • タイムスタンプ str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

method update_image_async (非同期)

このスレッドが所有する1つのイメージを非同期に更新します。

既存のバイトを保持するには、imageを省略します。imageを指定する場合は、mime_typeを指定する必要があります。既存の説明を保持するには、descriptionを省略します。Noneを渡して、構成されたLLMで新しい説明を生成します。nullでない説明によって、その説明が直接置き換えられます。メタデータ、タイムスタンプおよび有効期限の設定は、指定すると更新されます。メッセージに添付されたイメージの有効期限は、update_message_async()を使用して変更する必要があります。

• 戻り値:更新されたイメージ識別子。
• 戻り型: str
• Raises: ValueError– メッセージに添付されたイメージに有効期限設定が指定されている場合。
• パラメータ:
  • image_id str
  • イメージ bytes
  • 説明 str | None
  • mime_type ImageMimeType
  • メタデータ dict[str, Any] | None
  • タイムスタンプ str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

メソッド update_memory

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

• パラメータ:
  • memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが更新されます。
  • content str– オプションの置換コンテンツ。格納されているコンテンツを置換する文字列を指定します。省略すると、格納されたコンテンツは保持されます。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として扱われます。
  • status RecordStatus– このメモリーに似たレコードの置換ライフサイクルステータス(オプション)。現在のステータスを保持するには、これを省略します。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメモリーに似たレコードの識別子。
• 戻り型: str

method update_memory_async (非同期)

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

• パラメータ:
  • memory_id str– メモリー識別子。格納されたthread_idがこのスレッドと完全に一致するメモリーに似たレコード(memory、guideline、fact、preference)のみが更新されます。
  • content str– オプションの置換コンテンツ。格納されているコンテンツを置換する文字列を指定します。省略すると、格納されたコンテンツは保持されます。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として扱われます。
  • status RecordStatus– このメモリーに似たレコードの置換ライフサイクルステータス(オプション)。現在のステータスを保持するには、これを省略します。
  • **kwargs (Any)– 予期しないキーワード引数が拒否されます。
• 戻り値:更新されたメモリーに似たレコードの識別子。
• 戻り型: str

例

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

メソッド update_message

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

• パラメータ:
  • message_id str– メッセージ識別子。格納されたthread_idがこのスレッドと完全に一致するメッセージのみが更新されます。
  • content str | list[Mapping[str, Any]]– オプションの置換メッセージ・コンテンツ。格納されたコンテンツを置換する文字列、またはテキストおよびイメージ・コンテンツ部分の順序付きシーケンスを指定します。省略すると、格納されたコンテンツは保持されます。空の文字列を使用して、空のテキスト・コンテンツで置換します。
  • 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 | list[Mapping[str, Any]]– オプションの置換メッセージ・コンテンツ。格納されたコンテンツを置換する文字列、またはテキストおよびイメージ・コンテンツ部分の順序付きシーケンスを指定します。省略すると、格納されたコンテンツは保持されます。空の文字列を使用して、空のテキスト・コンテンツで置換します。
  • 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が変更されたときに元の有効期限を保持することに注意してください。

例

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

メソッド update_record_link

エンドポイントがこのスレッドによって所有されているリレーションを更新します。

省略された値は保持されます。relation_typeが組込みメモリー・リレーション型に変更されると、その固定逆ラベルがopposite_relation_typeに置換されます。

• パラメータ:
  • relation_id str– スレッド所有のリレーションの識別子。
  • relation_type str– オプションの置換ソースとターゲットのラベル。
  • opposite_relation_type str– オプションの置換逆方向ラベル。格納されているラベルを保持するには、これを省略します。
  • timestamp str | None– オプションの置換タイムスタンプ。Noneを渡してクリアします。
  • metadata dict[str, Any] | None– オプションの置換メタデータ。格納されたオブジェクトを置き換えます。
• 戻り値:更新されたリレーションの数(0または1)。
• 戻り型: int

例

thread.update_record_link("relation-id", relation_type="supports")
1

method update_record_link_async (非同期)

エンドポイントがこのスレッドに属しているリレーションを非同期的に更新します。

• パラメータ:
  • relation_id str
  • relation_type str
  • opposite_relation_type str
  • タイムスタンプ str | None
  • メタデータ dict[str, Any] | None
• 戻り型: int

メソッド 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– 以前のバックグラウンド抽出が終了する前にタイムアウトが期限切れになると発生します。
• 戻り型:なし

例

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

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

メッセージとメッセージの内容

クラス oracleagentmemory.apis.message.Message

ベース: object

スレッドおよびLLMアダプタで共有されるインメモリー・メッセージ。

• パラメータ:
  • role str– メッセージの役割。スレッド・メッセージには、カスタム・ロール名を使用できます。
  • content str | collections.abc.Sequence[oracleagentmemory.apis.message.MessageContent]– メッセージ・テキスト、またはTextContentおよびImageContentパートの順序付きシーケンス。コンテンツ・シーケンスは空にできません。また、不変タプルとして格納されます。
  • timestamp str | None– メッセージに関連付けられたオプションのタイムスタンプ。
  • metadata dict[str, Any] | None– メッセージに関連付けられたオプションのJSON互換メタデータ。
  • id str | None– オプションの安定したメッセージ識別子。メッセージが識別子なしで追加されると、ストアによって生成されます。

クラス oracleagentmemory.apis.message.MessageContent

ベース: ABC

構造化メッセージ・コンテンツのベース・クラス。

• パラメータ:
  • id str– このコンテンツ・パートの安定した識別子。省略すると自動的に生成されます。
  • timestamp str | None– このコンテンツ・パートに関連付けられたオプションのタイムスタンプ。

クラス oracleagentmemory.apis.message.TextContent

ベース: MessageContent

マルチモーダル・メッセージのテキスト部分。

• パラメータ:
  • text str– このコンテンツ部分によって継承されるテキスト。
  • id str–MessageContentから継承された安定した識別子。省略すると自動的に生成されます。
  • timestamp str | None–MessageContentから継承されたオプションのタイムスタンプ。

クラス oracleagentmemory.apis.message.ImageContent

ベース: MessageContent

マルチモーダル・メッセージのイメージ部分。

• パラメータ:
  • bytes bytes | None– 使用可能な場合はイメージ・データ。Noneは、メッセージにイメージ・バイトをロードせずにイメージ・メタデータが含まれている場合に許可されます。
  • mime_type oracleagentmemory.apis.message.ImageMimeType– イメージMIMEタイプ。
  • description str | None– イメージを説明するオプションのテキスト。Noneの場合、高レベルのイメージおよびメッセージAPIは、構成されたLLMを使用して説明を生成できます。
  • id str–MessageContentから継承された安定した識別子。省略すると自動的に生成されます。
  • timestamp str | None–MessageContentから継承されたオプションのタイムスタンプ。

クラス oracleagentmemory.apis.message.ImageMimeType

ベース: str、Enum

イメージ・コンテンツでサポートされるMIMEタイプ。

アニメーション形式PNGとWebPはサポートされていません。

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'image/WEBP'

コンテキスト・カード

クラス 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'