f(入力コンテキスト) → 構造化出力

┌─────────────────────────────────────────┐
│  🍞 Pre-Processing Layer（上パン）         │
│  入力の正規化・バリデーション・コンテキスト構築  │
├─────────────────────────────────────────┤
│  🥩 LLM Core Layer（フィリング）           │
│  推論・判断・構造化出力の生成                │
├─────────────────────────────────────────┤
│  🍞 Post-Processing Layer（下パン）        │
│  出力パース・品質チェック・副作用の実行        │
└─────────────────────────────────────────┘

import anthropic
from pydantic import BaseModel, ValidationError
from typing import Optional
import logging

# 構造化出力のスキーマ定義
class TaskAnalysis(BaseModel):
    intent: str
    required_tools: list[str]
    confidence: float
    reasoning: str

class SandwichAgent:
    def __init__(self, client: anthropic.Anthropic):
        self.client = client
        self.logger = logging.getLogger(__name__)

    # ─────────────────────────────────────
    # 上パン：Pre-Processing Layer
    # ─────────────────────────────────────
    def preprocess(self, raw_input: str, context: dict) -> dict:
        """入力の正規化・バリデーション・コンテキスト構築"""
        # バリデーション
        if not raw_input or len(raw_input.strip()) == 0:
            raise ValueError("入力が空です")
        if len(raw_input) > 10000:
            raise ValueError("入力が上限を超えています")

        # コンテキスト構築
        return {
            "user_input": raw_input.strip(),
            "available_tools": context.get("tools", []),
            "user_id": context.get("user_id"),
            "session_id": context.get("session_id"),
        }

    # ─────────────────────────────────────
    # 中身：LLM Core Layer
    # ─────────────────────────────────────
    def call_llm(self, preprocessed: dict) -> dict:
        """LLMに推論を委ねる（構造化出力を強制）"""
        tools_desc = ", ".join(preprocessed["available_tools"]) or "なし"

        prompt = f"""以下のユーザー入力を分析し、JSON形式で回答してください。

ユーザー入力: {preprocessed["user_input"]}
利用可能なツール: {tools_desc}

必ず以下のJSONスキーマに従って出力してください:
{{
  "intent": "ユーザーの意図（1文）",
  "required_tools": ["必要なツール名のリスト"],
  "confidence": 0.0〜1.0の確信度,
  "reasoning": "判断の根拠"
}}"""

        response = self.client.messages.create(
            model="claude-opus-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}]
        )

        return {
            "raw_output": response.content[0].text,
            "usage": {
                "input_tokens": response.usage.input_tokens,
                "output_tokens": response.usage.output_tokens,
            }
        }

    # ─────────────────────────────────────
    # 下パン：Post-Processing Layer
    # ─────────────────────────────────────
    def postprocess(self, llm_result: dict, max_retries: int = 2) -> Optional[TaskAnalysis]:
        """出力パース・バリデーション・フォールバック"""
        import json

        raw = llm_result["raw_output"]

        # JSON抽出（LLMが余分なテキストを含む場合に対応）
        try:
            start = raw.index("{")
            end = raw.rindex("}") + 1
            json_str = raw[start:end]
            data = json.loads(json_str)
        except (ValueError, json.JSONDecodeError) as e:
            self.logger.error(f"JSONパース失敗: {e}, raw: {raw[:200]}")
            return None

        # 型安全なバリデーション
        try:
            result = TaskAnalysis(**data)
        except ValidationError as e:
            self.logger.error(f"スキーマ検証失敗: {e}")
            return None

        # 品質チェック
        if result.confidence < 0.3:
            self.logger.warning(f"確信度が低すぎます: {result.confidence}")
            # 低確信度はエスカレーション候補としてマーク

        # 可観測性：メトリクス記録
        self.logger.info(
            "llm_call_completed",
            extra={
                "input_tokens": llm_result["usage"]["input_tokens"],
                "output_tokens": llm_result["usage"]["output_tokens"],
                "confidence": result.confidence,
            }
        )

        return result

    # ─────────────────────────────────────
    # オーケストレーション
    # ─────────────────────────────────────
    def run(self, user_input: str, context: dict) -> Optional[TaskAnalysis]:
        """三層を順番に実行するコントロールフロー"""
        try:
            preprocessed = self.preprocess(user_input, context)
            llm_result = self.call_llm(preprocessed)
            return self.postprocess(llm_result)
        except ValueError as e:
            self.logger.error(f"前処理エラー（入力不正）: {e}")
            raise
        except anthropic.APIError as e:
            self.logger.error(f"LLM APIエラー: {e}")
            raise


# 使用例
if __name__ == "__main__":
    client = anthropic.Anthropic()
    agent = SandwichAgent(client)

    result = agent.run(
        user_input="先月の売上レポートを作成して、CSVでダウンロードできるようにしてほしい",
        context={"tools": ["database_query", "csv_export", "file_upload"], "user_id": "u-123"}
    )

    if result:
        print(f"意図: {result.intent}")
        print(f"必要なツール: {result.required_tools}")
        print(f"確信度: {result.confidence:.2f}")

def run_with_loop(self, task: str, max_iterations: int = 5) -> str:
    """終了条件を決定論的に管理するループ"""
    history = []
    
    for iteration in range(max_iterations):  # 最大反復数はコードで管理
        result = self.run(task, context={"history": history})
        
        if result is None:
            return "エラー: 処理を中断しました"
        
        history.append(result)
        
        # 終了条件の判定はLLMではなくコードで行う
        if result.confidence > 0.9 and "complete" in result.intent.lower():
            self.logger.info(f"タスク完了: {iteration + 1}回目")
            return result.reasoning
    
    # 最大反復数に達した場合はエスカレーション
    self.logger.warning("最大反復数に達しました。人間にエスカレーションします。")
    return "ESCALATE_TO_HUMAN"

# ❌ 悪い例：LLM呼び出し後にバリデーション
result = call_llm(raw_input)
if not is_valid(result):
    pass  # トークンコストをかけた後で失敗

# ✅ 良い例：入力時にバリデーション
validated = validate_input(raw_input)  # ここで失敗させる
result = call_llm(validated)

import pytest
from unittest.mock import MagicMock

class TestSandwichAgent:
    def test_preprocess_rejects_empty_input(self):
        """前処理レイヤーは単体でテスト可能"""
        agent = SandwichAgent(client=MagicMock())
        with pytest.raises(ValueError, match="入力が空"):
            agent.preprocess("", {})

    def test_postprocess_handles_malformed_json(self):
        """後処理レイヤーも単体でテスト可能"""
        agent = SandwichAgent(client=MagicMock())
        result = agent.postprocess({"raw_output": "これはJSONではありません", "usage": {}})
        assert result is None  # フォールバックが正しく機能する

    def test_full_pipeline_with_mock_llm(self):
        """LLMをモックして統合テスト"""
        mock_client = MagicMock()
        mock_client.messages.create.return_value = MagicMock(
            content=[MagicMock(text='{"intent": "売上レポート作成", "required_tools": ["db"], "confidence": 0.95, "reasoning": "test"}')],
            usage=MagicMock(input_tokens=100, output_tokens=50)
        )
        agent = SandwichAgent(client=mock_client)
        result = agent.run("売上レポートを作って", context={"tools": ["db"]})
        assert result is not None
        assert result.confidence == 0.95

# ❌ 悪い例
{"name": "get_data", "description": "データを取得する"}

# ✅ 良い例
{
    "name": "get_sales_report",
    "description": "指定期間の売上データをデータベースから取得する。期間はISO 8601形式（YYYY-MM-DD）で指定する。",
    "input_schema": {
        "type": "object",
        "properties": {
            "start_date": {"type": "string", "format": "date"},
            "end_date": {"type": "string", "format": "date"}
        },
        "required": ["start_date", "end_date"]
    }
}