Agent

agent ドメイン（src/ragspine/agent/）は RAGSpine のオーケストレーターです。そのモジュール docstring は、担当するフローを次のように要約しています。

意图解析 → 澄清网关 → 安全门 → 三路分流 → tool-use 循环 → 合成回答

（意図解析 → 明確化ゲートウェイ → セキュリティゲート → 三路ルーティング → tool-use ループ → 回答の合成）

公開エントリポイントはただ 1 つ — answer_question — であり、ここが捏造防止ガードの置かれている場所でもあります。概念については 捏造防止 を、ルーティングモデルについては 二重チャネル を参照してください。

レイアウト

intent — 4 スロット解析

intent.py は、IntentParser Protocol の背後で、生の質問を ParsedIntent dataclass に解析します。デフォルトの RuleIntentParser は LLM を一切使わず、設定駆動で、モジュールレベルの parse_intent(question, reference_date=None) に委譲します。

ParsedIntent はさらに route、raw_question、複数値スロットの metrics / entities / periods（明示的に列挙された複合クエリ用）、および external_entity を保持します。ルーティング定数は ROUTE_STRUCTURED = "structured"、ROUTE_NARRATIVE = "narrative"、 ROUTE_COMPOSITE = "composite" です。認識されたメトリックにナラティブの手がかりが伴えば composite に、数値の手がかりがあれば structured に、それ以外は narrative にルーティングされます。

intent — 明確化ゲートウェイ

clarify_scope(intent, reference_date=None) -> ClarificationResult は、いかなるチャネルよりも前に実行されます。 4 つのモードは次のとおりです:

この非対称性は意図的なものです: メトリックの欠落はまず質問し（narrowing_options = サポートされているメトリック一覧）、エンティティや期間の欠落は仮定を明示した上で回答します — ホームエンティティ（profile.home_entity_code）と直近の完了した会計年度 （("FY", str(ref.year - 1))）をデフォルトとし、その両方を assumption_note で開示し、 ワンクリックでの絞り込みを提供します。スコープ外の拒否は、ナラティブの早期リターンやメトリックチェックよりも先に、 intent.raw_question に対してセキュリティゲートを呼び出すことでチェックされます — 意図的に intent.external_entity を信用しません。

ClarificationResult のフィールド: mode、assumed_slots、assumption_note、 narrowing_options、question。

security_gate — 決定論的、決してプラガブルにしない

security_gate.py には SecurityGate(external_entities, home_company_name) があります。これは 決定論的で、LLM を呼ばず、企業名をハードコードしません — 競合他社リストとホーム企業名は DomainProfile から供給されます。

• detect(text) -> SecurityScreen — 最長一致による外部/競合エイリアス検出。空白を除去したビュー上でマッチし （そのため "竞 安" では回避できません）、ヒット箇所を同じ長さのスペースでマスクして、 漏洩しうる部分文字列を一切残しません（ドキュメント化されている 中国 → ACME_CN の衝突にも対応しています）。
• screen(*, raw_question, metric) -> SecurityVerdict — スコープを生の質問のみから再導出します。 競合ヒット時には SECURITY_REFUSE_OUT_OF_SCOPE （= "out_of_scope_entity"、意図的に CLARIFY_OUT_OF_SCOPE_ENTITY と同じ値）を、 拒否メッセージと「代わりに home_company_name について質問する」という絞り込みオプション付きで返します。それ以外は SECURITY_ALLOW を返します。

query_tools — query_metric の三状態

query_tools.py は、構造化チャネル唯一のファクト生成プリミティブである function-calling ツール query_metric を定義します。execute_query_metric(store, metric, entity, period, channel="TOTAL") はすべてのパラメータを用語集（glossary）を通して正規化し、 fact_metric ストアに問い合わせ、正確に 3 つのステータスのいずれかを返します — 決して推測はしません:

ツールスキーマはプロファイル由来です（build_query_metric_tool_anthropic / build_query_metric_tool_openai、加えて事前構築済みの定数）。したがってエンティティの例は 有効なプロファイルから供給されます — 企業名がハードコードされることは決してありません。

llm_provider — プラガブルなシーム

0.3.0 以降、LLMProvider Protocol はファミリー共有コアの corespine が所有し、ragspine.agent.llm_provider から 再エクスポートされます。これは OpenAI chat-completions 形式を話し、単一の chat メソッドを持ちます:

from corespine import ChatCompletion  # re-exported via ragspine.agent.llm_provider


class LLMProvider(Protocol):
    def chat(
        self,
        messages: list[dict[str, Any]],
        *,
        tools: list[dict[str, Any]] | None = None,
    ) -> ChatCompletion: ...

messages は OpenAI 形式の履歴（各要素は {"role", "content", ...}）です。システムプロンプトは 独立した引数ではなく、単に先頭の {"role": "system", ...} エントリです。 ChatCompletion は choices: tuple[Choice, ...]（各 Choice は content とオプションの tool_calls を持つ ResponseMessage をラップします）に加え、usage、model、id を保持します — 標準的な chat-completions エンベロープであり、すべて corespine の frozen dataclass です。

DEFAULT_ANTHROPIC_MODEL = "claude-opus-4-8"。チャット用の OpenAIProvider はまだ同梱されていません — ドキュメント化されたシームがあるだけです（OpenAI のツールスキーマは query_tools.py で既に事前構築されており、 [llm] extra は埋め込みバックエンド用に openai を同梱しています）。ProviderError （corespine.CorespineError のサブクラス）がラップするのはネットワーク/API/タイムアウトのエラーのみで、 プログラムエラーはそのまま伝播します。

agent — オーケストレーターと tool-use ループ

answer_question が唯一の公開エントリです:

def answer_question(
    question: str,
    store: FactStore,
    provider: LLMProvider,
    *,
    reference_date: date | None = None,
    narrative_retriever: NarrativeRetriever | None = None,
    intent_parser: IntentParser | None = None,
    decomposer: QueryDecomposer | None = None,
    history: Sequence[HistoryTurn] | None = None,
) -> AgentResult: ...

HistoryTurn は tuple[str, str] です。履歴は生成時のコンテキストとしてのみ使われます: システムメッセージの後、 現在の質問の前に挿入されますが、決定論的な意図解析、セキュリティスクリーニング、検索クエリ、 証拠/出典リストには決して入りません。アシスタントロールとして扱われるのは assistant のみで、 未知のロールは user に正規化されます。その結果、過去の会話テキストが競合他社クエリを許可したり、 引用になったりすることはありません。 ADR 0017 を参照してください。

そのフローは次のとおりです: リクエスト id を割り当て → プライバシーに配慮した trace コンテキストを構築 → 意図を解析（デフォルトは RuleIntentParser）→ clarify_scope。その後、厳密な順序で早期リターンします:

tool loop（_run_tool_loop）は MAX_TOOL_ITERATIONS = 5 で上限が設けられています: provider.chat(messages, tools=tools) を呼び出し、query_metric ツール呼び出しがあれば実行し、その結果を user メッセージとしてフィードバックし、モデルがツール呼び出しを返さなくなったら停止します。ProviderError の際には、 捏造する代わりに、固定の数値を含まないテキストへ縮退します。

answer_question は AgentResult を返します:

捏造防止ガード

「モデルの出力にかかわらず not-found に書き換える」ガードは _structured_answer にあります。 ツール結果をステータスごとに分割し、意図的にパスごとに分かれています:

• Found → 回答はファクト値から決定論的に合成され、モデルの文章は破棄されます （回帰テスト test_found_path_discards_fabricated_extra_number がこれを固定しています）。
• found なし、not_found あり → 誠実な拒否（「查不到 … 不提供任何推测数字」）。
• unrecognized_param のみ → 問題のパラメータを名指しします。
• ツール結果ゼロ（モデルがツールを呼ばずに回答した）→ モデルのテキストをそのまま返します。

複数サブタスクのパス（_multi_subtask_answer）はそもそも LLM を一切呼びません。ナラティブパス （_run_narrative）はモデルの文章を信頼しますが、モデルが名前を挙げ損ねた引用元ドキュメントを 強制的に追記します。trace フラグ fabrication_guard_triggered は、ツール結果が存在するのに どれも found でない場合 — すなわちガードが拒否へ書き換えた場合 — に true になります。

例

from ragspine.agent.agent import answer_question
from ragspine.agent.llm_provider import MockProvider
from ragspine.storage.fact_store import SqliteFactStore

store = SqliteFactStore("data/fact_metric.db"); store.init_schema()
result = answer_question("中国内地FY2024的REVENUE是多少", store, MockProvider())
print(result.answer)   # deterministic value, or an honest "not found"
print(result.sources)  # [{'doc': ..., 'locator': ...}]

関連ページ