スレッド

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

Oracleスレッド

クラス oracleagentmemory.core.OracleThread

ベース: IThread

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

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

ノート:

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

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

• パラメータ:
  • 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_window int– 抽出中にLLMにコンテキストとして提供する最新のメッセージ(新しく追加されたメッセージを含む)の数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。デフォルトは-1です。
  • context_summary_update_frequency int– 抽出コンテキスト・サマリーを更新するまでのメッセージ数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ要約されます。デフォルトは-1です。
  • memory_extraction_frequency int– メモリー抽出がトリガーされるまでのメッセージの数。-1に設定すると、新しく追加されたメッセージの全バッチを使用して、add_messagesコールごとに1回のみ抽出されます。
  • memory_extraction_token_limit int– メモリーの抽出およびサマリー更新の実行に使用されるLLMプロンプトの最大サイズ(トークン単位)。長いプロンプトは切り捨てられます。負または0の場合、プロンプトの切捨ては無効になります。
  • context_card_token_limit int– コンテキストカードのサマリーに使用されるLLMプロンプトの最大サイズ(トークン単位)。デフォルトは100_000トークンです。長いプロンプトは切り捨てられます。負または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がこのスレッドと完全に一致するメモリーに似たレコード(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– 取得およびレンダリングのフォールバック・サマリー・テキストを導出する際に使用する最新のメッセージの数。
  • max_relevant_results int– 含める取得された永続レコードの最大数。
  • max_recent_messages int–verbatimを埋め込む後続のrawメッセージの最大数。
  • **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

method get_context_card_async (非同期)

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

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

メソッド 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が発生します。
• 戻り値:合成スレッド・サマリー・テキストを含むサマリー・オブジェクト。
• 戻りタイプ: 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

ノート: 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'