二重チャネル

RAGSpine は、根本的に異なる 2 種類の質問に対して、根本的に異なる 2 つのメカニズムで回答します — そして、質問がどちら(または両方)を必要とするかは、単一のエージェントが判断します。

• 「数値はいくつか?」 → 構造化チャネル: ファクトテーブルと function-calling。決定論的であり、値の合成は行いません。
• 「なぜ / 何が起きたのか?」 → ナラティブチャネル: ドキュメントチャンクに対するハイブリッド検索、オプションのリストワイズ再ランキング、そして引用付きの LLM 合成。

ルーターは agent/agent.py(answer_question)にあり、インテント解析と確認ゲートは agent/intent.py にあります。

エージェントのルーティング方法

すべての質問はまず、LLM を一切使わない設定駆動のルールパーサー(RuleIntentParser、IntentParser Protocol の背後で差し替え可能)によって 4 つのインテントスロット に解析されます:

ルーティングは、解析されたスロットと語彙的な手がかりから決定されます(parse_intent):

ルーティングの前に、確認ゲートウェイ(clarify_scope)が意図的な非対称性を適用します:

• metric の欠落 → まず質問する(メトリックの推測は実質的な誤りにつながるため)。
• entity / period の欠落 → 仮定を明示した上で回答する(デフォルトはホームグループ / 直近の完了した会計年度とし、仮定を明示し、ワンクリックでの絞り込みを提供します)。
• スコープ外 / 競合他社のエンティティ → いずれのチャネルも実行する前に拒否します(RESTRICTED の隔離 と決定論的セキュリティゲートを参照)。

構造化チャネル: found / not_found / unrecognized の三状態

構造化チャネルにおいてファクトを生成する唯一のプリミティブは query_metric ツール(agent/query_tools.py)です。その実行関数は各パラメータを用語集を通じて正規化し、fact_metric ストアに問い合わせます。返されるのは 3 つ のステータスのいずれかであり — 決して推測ではありません:

{
  "status": "found",
  "value": 1320,
  "unit": "USD_M",
  "metric_code": "REVENUE",
  "entity": "ACME_CN",
  "period_type": "FY",
  "period": "2024",
  "channel": "TOTAL",
  "source": { "doc": "ACME_FY2024_Review.pptx", "locator": "slide=2,table=1,row=REVENUE,col=FY2024" }
}

{
  "status": "not_found",
  "normalized": { "metric_code": "REVENUE", "entity": "ACME_CN", "period": "2025", "channel": "TOTAL" }
}

{ "status": "unrecognized_param", "param": "entity", "raw": "some unknown company" }

ナラティブチャネル

ルートが narrative の場合、エージェントは注入された NarrativeRetriever を呼び出します(_run_narrative)。デフォルトのチェーン(retrieval/)は次のとおりです:

リトリーバーが接続されていない場合、または検索が何も返さない場合、ナラティブチャネルは回答を捏造するのではなく、誠実に縮退します(「未検索 / 未接続」)。

複合パス: 両方を実行し、比較し、マージする

複合的な質問に対しては、エージェントはまず構造化パスを実行し、次にナラティブパスを実行してマージします:

<structured answer, with the number(s) + lineage>

归因分析：
<narrative answer, synthesized from cited snippets>

両チャネルの出典は連結されます。構造化側が複数のサブタスク(ユーザーが明示的に列挙した複数のメトリック / エンティティ / 期間)に展開される場合、エージェントは各 query_metric サブタスクを LLM を使わずに決定論的に 実行し(_multi_subtask_answer)、比較可能な期間がちょうど 2 つの場合には、その差分を自ら計算します。