コンポーネント一覧

コンポーネント一覧¶

このページでは、Marionetteで利用できるすべてのコンポーネント（Item）について、入力・出力・機能・処理タイミングをまとめています。

コンポーネント一覧（サマリ表）¶

処理タイミングについて¶

各コンポーネントは、is_lastフラグに応じて処理タイミングを制御できます。詳細はストリーミングによる高速化を参照してください。

各コンポーネントの詳細¶

Entry（エントリー）¶

ドラマの開始点となる特殊なコンポーネントです。event.triggerからの情報を受け取り、ドラマの処理を開始します。

設定項目:

# output_itemsの例
{
  "data": "lambda message_data: message_data",
  "reason": "lambda message_data: message_data.get('reason', '')"
}

DialogAdd（ダイアログ追加）¶

会話履歴にエントリを追加するコンポーネントです。

設定項目:

# phaseが変化したときのみ追加
lambda _: prev_states and prev_states.get('conversation', {}).get('phase') != states.conversation.phase

DialogHistory（ダイアログ履歴）¶

会話履歴を取得してリスト形式で出力するコンポーネントです。

設定項目:

dialog_history_configのデフォルト:

{
  "role_filter": ["user*", "assistant"],
  "max_history_items": 10,
  "delete_history_steps": 5
}

出力形式:

[
  {"role": "user", "text": "こんにちは", "meta": None},
  {"role": "assistant", "text": "こんにちは！", "meta": {"emotion": "happy"}}
]

StateSet（状態設定）¶

状態（States）を更新するコンポーネントです。

設定項目:

update_statesの例:

{
  "chain.count": "lambda: values.count + 1",
  "user.name": "{{ values.name }}"
}

# 値が空の場合は更新をスキップ
"user.name": "lambda: values.name if values.name else Skip()"

Gate（ゲート）¶

条件がTrueになった時点でメッセージをパススルーするコンポーネントです。

設定項目:

triggerの例:

# ステータスが'ready'になったらパススルー
lambda: values.status == 'ready'

# 30秒経過したらパススルー
lambda: (time.time() - (states.start_timestamp or 0)) >= 30

# prev_statesで状態変化を検出
lambda: prev_states and prev_states.conversation.phase != states.conversation.phase

SelfTrigger（セルフトリガー）¶

同じドラマを繰り返し起動するためのコンポーネントです。ユーザー入力なしで自動的に連続対話を行う場合などに使用します。

設定項目:

execution_modeの種類:

triggerの例:

# カウンターが5未満の場合にトリガー
lambda: int(states.counter or 0) < 5

# should_continueフラグがTrueの場合にトリガー
lambda: states.should_continue == True

message_dataの例:

# 理由とカウンターを渡す
lambda: {'reason': 'self_trigger', 'count': int(states.counter or 0)}

EventResponse（イベントレスポンス）¶

WebSocketを通じてクライアントにメッセージを送信するコンポーネントです。

設定項目:

modeの種類:

LambdaFunc（ラムダ関数）¶

任意のカスタム関数を実行するコンポーネントです。

設定項目:

process_modeの種類:

関数の基本形:

async def my_func(input_message, output_message):
    # 入力値を取得
    text = input_message.values.response.x

    # 処理を実行
    processed = text.upper()

    # 出力（is_lastを適切に設定）
    await output_message.update('result', processed, is_last=True)

if 'count' not in buffer:
    buffer['count'] = 0
buffer['count'] += 1

PublicLLM（パブリックLLM）¶

外部LLMサービス（OpenAI、Anthropic、Gemini）を呼び出すコンポーネントです。

設定項目:

ストリーミングと構造化出力:

GeppettoLLM（キャラクターLLM）¶

Geppetto LLMサービスを呼び出すコンポーネントです。キャラクター対話用に最適化されています。

設定項目:

特徴:

• SSE（Server-Sent Events）プロトコルによるストリーミング
• Sticky Sessionによるセッション維持（KVキャッシュ活用）
• ループ検出機能（同じ応答が繰り返される場合に検出・対処）
• post_cutによる自動停止（stop_wordsの部分一致検出）

SystemLLM（システムLLM）¶

システム用途のLLMサービスを呼び出すコンポーネントです。

設定項目:

GeppettoLLMとの違い:

TTS3（音声合成）¶

テキストを音声に変換するコンポーネントです。

設定項目:

出力形式:

{
    "audio": "base64エンコードされた音声データ",
    "chunk_id": 0,  # チャンクID
    "is_last": False  # 最後のチャンクか
}

# この設定の場合、values.decoration_idの確定を待ってから音声合成開始
decoration_id: "{{ values.decoration_id if values.decoration_id else 'neutral' }}"

RAG（ドキュメント検索）¶

キーワードマッチングまたはEmbedding類似度検索を使用してドキュメントを検索するコンポーネントです。

設定項目:

documents（CSV形式）の例:

"doc1", "Pythonはプログラミング言語です"
"doc2", "JavaScriptはWeb開発で使われます"
"doc3", "Rustはシステムプログラミング言語です"

検索方式（search_method）の選択:

Classifier（テキスト分類）¶

NCA（Neighborhood Component Analysis）とKNNを使用してテキストを分類するコンポーネントです。

設定項目:

classes（CSV形式）の例:

"greeting", "こんにちは"
"greeting", "おはよう"
"greeting", "こんばんは"
"farewell", "さようなら"
"farewell", "またね"

RAGとの違い:

Parser（パーサー）¶

ストリーミング入力から指定したパターンを切り出し、複数の出力変数に分離するコンポーネントです。
LLMの出力を感情・発話・アクションなどに分けてTTSや動作制御に渡す場合に便利です。

設定項目:

patternsの形式:

[
  {"start": "開始文字列", "end": "終了文字列", "output": "出力変数名"}
]

特殊な値:

使用例1: 括弧パターン¶

LLMが 【感情】発話テキスト（アクション） の形式で出力する場合：

[
  {"start": "【", "end": "】", "output": "emotion"},
  {"start": "】", "end": "（", "output": "speech"},
  {"start": "（", "end": "）", "output": "action"}
]

入力:

【嬉しい】こんにちは！元気ですか？（手を振る）

出力:
- emotion: "嬉しい"
- speech: "こんにちは！元気ですか？"
- action: "手を振る"

使用例2: タグパターン¶

LLMが [emotion:xxx][voice:yyy]テキスト の形式で出力する場合：

[
  {"start": "[emotion:", "end": "]", "output": "emotion"},
  {"start": "[Emotion:", "end": "]", "output": "emotion"},
  {"start": "[voice:", "end": "]", "output": "voice"}
]

使用例3: 行頭・行末パターン¶

各行を個別に出力する場合：

[
  {"start": "", "end": "", "output": "line"}
]

入力:

行1のテキスト
行2のテキスト
行3のテキスト

出力:
- line: "行1のテキスト" → "行2のテキスト" → "行3のテキスト" と順次出力

ストリーミング対応¶

Parserはストリーミング入力に対応しています：

• 入力が少しずつ来ても正しくパースします
• 開始文字列を検出したら、対応する出力変数へのストリーミング出力を開始します
• 終了文字列を検出したら、is_last=Trueで出力を確定します

デッドロック防止¶

入力のis_last=Trueを受信した時点で、定義されたすべての出力変数に対してis_last=Trueを送信します。
これにより、パターンが崩れた場合でも後続のコンポーネントがデッドロックすることを防ぎます。

Group（グループ）¶

Groupは、複数のItemを組み合わせて再利用可能なコンポーネントとして扱う機能です。

Group専用のItem（UI上の仮想エレメント）¶

エディタ上でGroupを作成する際、以下の仮想エレメントを使用してグループの入口と出口を定義します。

環境変数¶

Groupでは、グループ専用の環境変数を設定できます。

# 自由式の中で参照
${変数名}

使用例:
同じGroupを複数箇所で使い、環境変数に異なる値を設定することで、異なる挙動を実現できます。

# Group1の設定
ai_name = "Tsuyoshi"

# Group2の設定（同じGroup）
ai_name = "Koichi"