모델 API 설계 - 100-hours-a-week/KTB4-13th-wiki GitHub Wiki

{
  "query": "김영하 여행의 이유",
  "filters": {
    "category": "에세이",
    "price_min": 10000,
    "price_max": 20000,
    "pub_year_from": 2020,
    "pub_year_to": 2026,
    "in_stock_only": true
  },
  "sort": "relevance",
  "cursor": null,
  "size": 15
}

{
  "message": "search_success",
  "data": {
    "results": [
      {
        "book_id": 2077,
        "title": "여행의 이유",
        "author": "김영하",
        "publisher": "문학동네",
        "price": 13500,
        "in_stock": true,
        "cover_url": "https://…/2077.jpg"
      }
    ],
    "next_cursor": "eyJ…(서명됨)",
    "fallback": null
  }
}

{
  "message": "search_success",
  "data": {
    "results": [],
    "next_cursor": null,
    "fallback": {
      "message": "원하는 책을 못 찾았어요. AI 추천에게 물어볼까요?"
    }
  }
}

{ "texts": ["쓸쓸하고 담담한 위로"], "purpose": "query" }

{
  "message": "embed_success",
  "data": {
    "vectors": [[0.0123, -0.0456, "…"]],
    "dim": 1024,
    "model": "bge-m3-2026q3"
  }
}

{
  "user_id": 123,
  "consented": true,
  "spec": { "…": "현재 추천 조건(6키 전체)" },
  "message": "너무 무겁지 않은 걸로",
  "recent_turns": [{ "role": "user", "text": "비 오는 날 읽을 책 추천해줘" }],
  "exclude_book_ids": [4021],
  "image_ref": null
}

{
  "intent": "semantic",
  "exact": { "title": null, "author": null, "publisher": null },
  "filters": {
    "category": "에세이",
    "price_max": 20000,
    "in_stock_only": true
  },
  "semantic": "비 오는 날 카페에서 읽을 잔잔한 책",
  "anchor_book": null,
  "exclude": [4021]
}

{
  "intent": "semantic",
  "exact": { "title": null, "author": null, "publisher": null },
  "filters": {},
  "semantic": null,
  "anchor_book": null,
  "exclude": []
}

{
  "message": "recommend_success",
  "data": {
    "reply": "비 오는 날 분위기에 맞춰 골라봤어요.",
    "spec": { "…": "갱신된 추천 조건(6키 전체)" },
    "recognition": null,
    "cards": [
      {
        "book_id": 1088,
        "rank": 1,
        "match_score": 87,
        "title": "달러구트 꿈 백화점",
        "author": "이미예",
        "price": 12420,
        "cover_url": "https://…/1088.jpg",
        "reason_short": "비 오는 날의 차분한 분위기와 어울리는 따뜻하고 가벼운 판타지예요.",
        "reason_long": "비 오는 날에 어울리는 책을 찾으셨죠. 꿈을 사고파는 상점이라는 설정을 따뜻한 문장으로 풀어내서, 창밖 빗소리와 같이 읽기 좋아요. 한 편이 짧게 끊겨 부담 없이 읽히고, 말씀하신 가격대도 넘지 않습니다.",
        "match_basis": [
          { "label": "분위기", "detail": "잔잔함" },
          { "label": "가격", "detail": "조건 충족" }
        ]
      }
    ],
    "followup": null,
    "buttons": [],
    "degraded": false
  }
}

{
  "message": "recommend_success",
  "data": {
    "reply": "이 책은 《달러구트 꿈 백화점》(이미예)예요. 잠든 사이 꿈을 사고파는 상점 이야기예요. 비슷한 결의 책도 함께 골라봤어요.",
    "spec": { "…": "anchor_book이 1088로 갱신된 추천 조건" },
    "recognition": { "recognized": true, "book_id": 1088, "candidates": [] },
    "cards": [{ "book_id": 4021, "rank": 1, "…": "일반 턴과 같은 카드 형식" }],
    "followup": null,
    "buttons": [
      { "label": "네", "action": "library_add", "book_id": 1088 },
      { "label": "아니요", "action": "dismiss" }
    ],
    "degraded": false
  }
}

{
  "message": "recommend_success",
  "data": {
    "reply": "이 책이 맞을까요? 비슷한 표지가 몇 권 있어요.",
    "spec": { "…": "anchor_book은 아직 갱신하지 않은 추천 조건(null 유지)" },
    "recognition": {
      "recognized": false,
      "book_id": null,
      "candidates": [
        {
          "book_id": 1088,
          "title": "달러구트 꿈 백화점",
          "author": "이미예",
          "cover_url": "https://…/1088.jpg",
          "confidence": 0.62
        },
        {
          "book_id": 4021,
          "title": "…",
          "author": "…",
          "cover_url": "…",
          "confidence": 0.55
        }
      ]
    },
    "cards": [],
    "followup": null,
    "buttons": [
      {
        "label": "달러구트 꿈 백화점",
        "action": "confirm_book",
        "book_id": 1088
      },
      { "label": "다시 찍기", "action": "retake" }
    ],
    "degraded": false
  }
}

{
  "message": "feed_success",
  "data": {
    "items": [
      {
        "book_id": 3310,
        "title": "아무튼, 산",
        "author": "장보영",
        "price": 9900,
        "cover_url": "https://…/3310.jpg",
        "in_stock": true,
        "match_score": 84
      }
    ],
    "next_cursor": "eyJ…(서명됨)",
    "cold_start": false
  }
}

{
  "user_id": 123,
  "consented": true,
  "conversation": [
    { "role": "user", "text": "비 오는 날 읽을 책 추천해줘" },
    { "role": "assistant", "text": "잔잔한 소설 위주로 골라봤어요." },
    { "role": "user", "text": "이별 후에 위로가 될 만한 걸로" }
  ],
  "conversation_id": "cv_20260903_a1",
  "existing_preferences": [
    { "type": "mood", "value": "잔잔한 에세이를 선호함" }
  ]
}

{
  "message": "extract_success",
  "data": {
    "extractions": [
      {
        "type": "mood",
        "value": "이별 후 위로되는 잔잔한 소설을 찾음",
        "confidence": 0.82,
        "vector": [0.01, -0.04, "…"],
        "dim": 1024,
        "source_conversation_id": "cv_20260903_a1"
      }
    ],
    "nothing_found": false
  }
}

{
  "user_id": 123,
  "idempotency_key": "prof_20260904_a1b2",
  "onboarding": {
    "reading_times": ["밤"],
    "criteria": ["베스트셀러"],
    "categories": ["에세이", "한국소설"],
    "tags": ["힐링", "성장"],
    "liked_book_ids": [1088, 3310]
  },
  "memories": [
    {
      "type": "author",
      "value": "김영하의 문장을 좋아함",
      "vector": [0.02, -0.01, "…"],
      "dim": 1024
    },
    {
      "type": "mood",
      "value": "이별 후 위로되는 잔잔한 소설을 찾음",
      "vector": [0.01, -0.04, "…"],
      "dim": 1024
    }
  ]
}

{
  "message": "profile_success",
  "data": {
    "cold_start": false,
    "profile_version": 3
  }
}

{
  "user_id": 123,
  "conversation_id": "cv_…",
  "message": "3만원 안에서 2권 골라 담아줘",
  "context_cards": [
    {
      "book_id": 1088,
      "rank": 1,
      "price": 13500,
      "match_score": 92,
      "in_stock": true
    },
    {
      "book_id": 4021,
      "rank": 2,
      "price": 14000,
      "match_score": 87,
      "in_stock": true
    },
    {
      "book_id": 3310,
      "rank": 3,
      "price": 12800,
      "match_score": 81,
      "in_stock": true
    }
  ],
  "focused_book_id": 1088,
  "user_context": { "logged_in": true, "has_default_address": true },
  "allow_tools": null,
  "idempotency_key": "idem_…"
}

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》 + 《아무튼, 산》 = 26,300원. 이 둘 담을까요?",
    "tool_calls": [
      {
        "name": "recommendations.candidates",
        "arguments": { "size": 20 },
        "result": {
          "count": 20,
          "candidates": [
            { "book_id": 1088, "match_score": 92 },
            { "book_id": 3310, "match_score": 81 },
            { "book_id": 4021, "match_score": 87 }
          ]
        },
        "grounded": true
      },
      {
        "name": "inventory.check",
        "arguments": { "book_ids": [1088, 3310, 4021] },
        "result": {
          "1088": { "price": 13500, "in_stock": true },
          "3310": { "price": 12800, "in_stock": true },
          "4021": { "price": 14000, "in_stock": true }
        },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "3만원 2권",
      "book_ids": [1088, 3310],
      "confidence": 0.9
    },
    "selection": {
      "goal": "budget_pick",
      "constraints": { "budget_total": 30000, "count": 2, "in_stock": true },
      "chosen": [
        { "book_id": 1088, "price": 13500, "match_score": 92 },
        { "book_id": 3310, "price": 12800, "match_score": 81 }
      ],
      "total_price": 26300,
      "alternatives_considered": 3
    },
    "buttons": [
      {
        "label": "담기",
        "action": "confirm_selection",
        "book_ids": [1088, 3310]
      },
      { "label": "다른 조합", "action": "reselect" }
    ]
  }
}

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》을 장바구니에 담았어요.",
    "tool_calls": [
      {
        "name": "cart.add",
        "arguments": { "book_id": 1088, "qty": 1 },
        "result": { "cart_count": 3 },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "1번",
      "book_ids": [1088],
      "confidence": 0.97
    },
    "selection": null,
    "buttons": [
      { "label": "장바구니 보기", "action": "navigate", "target": "CART-001" }
    ]
  }
}

{
  "message": "agent_success",
  "data": {
    "reply": "어떤 책 말씀이실까요? 방금 추천한 1번 《달러구트 꿈 백화점》이 맞을까요?",
    "tool_calls": [],
    "resolved_reference": {
      "ref": "그 책",
      "book_ids": [],
      "confidence": 0.41
    },
    "selection": null,
    "buttons": [
      { "label": "네, 1번", "action": "confirm_reference", "book_id": 1088 },
      { "label": "아니요", "action": "dismiss" }
    ]
  }
}

{
  "message": "agent_success",
  "data": {
    "reply": "1번은 문장이 담백해 부담이 적고, 3번은 화제작인데 호흡이 무거워요. 가격은 700원 차이(1번 13,500 / 3번 12,800), 별점은 1번 4.6, 3번 4.4예요.",
    "tool_calls": [
      {
        "name": "book.detail",
        "arguments": { "book_id": 1088 },
        "result": { "price": 13500, "rating_avg": 4.6 },
        "grounded": true
      },
      {
        "name": "book.detail",
        "arguments": { "book_id": 3310 },
        "result": { "price": 12800, "rating_avg": 4.4 },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "1번, 3번",
      "book_ids": [1088, 3310],
      "confidence": 0.95
    },
    "selection": null,
    "buttons": [
      { "label": "1번 담기", "action": "confirm_reference", "book_id": 1088 }
    ]
  }
}

{
  "message": "agent_success",
  "data": {
    "reply": "주문 상태는 주문내역에서 확인하실 수 있어요.",
    "tool_calls": [],
    "resolved_reference": null,
    "selection": null,
    "buttons": [
      { "label": "주문내역", "action": "navigate", "target": "ORDER-LIST-001" }
    ]
  }
}

{
  "status": "degraded",
  "version": "a1b2c3d",
  "replication_lag_seconds": 4,
  "components": {
    "gateway": "ok",
    "database": "ok",
    "vector_index": "ok",
    "llm": "unavailable",
    "embedding": "ok"
  }
}