スレッド

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

Oracleスレッド

クラス oracleagentmemory.core.OracleThread

ベース: IThread

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

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

ノート:

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

新規スレッド・ハンドルを作成します。

• パラメータ:
  • store OracleMemoryStore– 埋込みレコードの永続化に使用される共有ストア・バックエンド。
  • thread_id str– スレッド識別子。指定しない場合、UUIDが生成されます。
  • user_id str– スレッドに関連付けられたユーザー識別子。省略すると、UUIDが生成されます。
  • agent_id str– スレッドに関連付けられたエージェント識別子。省略すると、UUIDが生成されます。
  • persist_messages_in_config bool– _to_configに最新のrawメッセージスナップショットを含めるかどうか。スレッド構成を介してメッセージ表コンテンツをエクスポートしないように、DBストアを使用するスレッドに対して自動的にFalseに設定されます。
  • LLM ILlm | None– メモリー抽出およびコンテキストサマリー更新に使用されるオプションのLLMアダプタ。指定した場合、add_messagesは、追加された各メッセージから関連するメモリーを抽出し、record_type="memory"として格納します。
  • memory_extraction_window int– 抽出中にLLMにコンテキストとして提供する最新のメッセージ(新しく追加されたメッセージを含む)の数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。デフォルトは-1です。
  • context_summary_update_frequency int– コンテキストサマリーを更新するまでのメッセージ数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ要約されます。トランスクリプト書込み中にスレッド要約メタデータをリフレッシュするために、同じ頻度が再利用されます。
  • memory_extraction_frequency int– メモリー抽出がトリガーされるまでのメッセージの数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。
  • memory_extraction_token_limit int– メモリー抽出で使用されるプロンプトの最大サイズ(トークン単位)。長いプロンプトは切り捨てられます。負または0の場合、切捨ては実行されません。
  • 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に従ってサマリーが更新されます。現在の要約は、記憶を抽出するときにコンテキストとして提供されます。
  • クライアント Any | None

例

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

メソッド add_memory

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

• パラメータ:
  • content str– メモリーとして格納するテキスト・コンテンツ。
  • user_id str– オプションのユーザー識別子のオーバーライド。
  • agent_id str– オプションのエージェント識別子のオーバーライド。
  • thread_id str– オプションのスレッド識別子のオーバーライド。
  • memory_id str– このメモリー行の呼び出し元提供の安定した識別子(オプション)。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメモリー・レコードの識別子。
• 戻り型: str

例

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

メソッド add_messages

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

• パラメータ:
  • messages list[Message | MessageT]– 追加するメッセージのリスト。メッセージは、Messageオブジェクトまたはroleおよびcontentのディクショナリ(およびオプションのid)です。
  • **store_kwargs (任意)– バッキングストアに転送されるストア固有の書き込みオプション。
• 戻り値:挿入されたメッセージ・レコードの識別子。
• 戻り型: list[str]

例

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

method add_messages_async (非同期)

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

• パラメータ:
  • メッセージ list[Message | MessageT]
  • store_kwargs Any
• 戻り型: list[str]

メソッド delete_memory

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

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

例

thread.delete_memory("456")
0

メソッド delete_message

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

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

ノート:

削除に成功すると、派生したスレッドサマリー状態がクリアされるため、あとでサマリーおよびコンテキストカードの呼び出しが残りのトランスクリプトから再構築されます。導出されたメモリーは、現在メッセージごとの来歴を保持していないため、自動的に削除されません。

例

thread.delete_message("123")
0

メソッド get_context_card

スレッドのXMLのようなコンテキスト・カードを返します。

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

• パラメータ:
  • fallback_message_count int– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。
  • max_relevant_results int– 含める取得された永続レコードの最大数。
  • max_recent_messages int–verbatimを埋め込む後続のrawメッセージの最大数。
  • **kwargs (Any)– 将来のコンテキストカードオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:最新のメッセージに基づくスレッド・コンテキスト・サマリーを含むカード。
• 戻り型: str

ノート:

これは、スレッドのデフォルトの検索スコープを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()
True

method get_context_card_async (非同期)

スレッドのXMLのようなコンテキスト・カードを非同期で返します。

• パラメータ:
  • fallback_message_count int– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。
  • max_relevant_results int– 含める取得された永続レコードの最大数。
  • max_recent_messages int–verbatimを埋め込む後続のrawメッセージの最大数。
  • **kwargs (Any)– 将来のコンテキストカードオプション用に予約されています。予期しないキーワード引数によりTypeErrorが発生します。
• 戻り値:最新のメッセージに基づくスレッド・コンテキスト・サマリーを含むカード。
• 戻り型: str

メソッド 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'

メソッド get_summary

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

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

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

例

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

method get_summary_async (非同期)

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

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

メッセージ

クラス oracleagentmemory.apis.thread.Message

ベース: object

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