AI 1 모델 API 명세 - 100-hours-a-week/KTB4-13th-wiki GitHub Wiki

키워드 검색과 벡터 검색을 각각 수행한 뒤, 제목이 검색어와 (공백 빼고) 똑같은 책을 맨 앞에 놓고 나머지는 두 순위를 RRF로 합쳐 최종 순위를 만든다. LLM을 호출하지 않는다. 요청에 담긴 필터와 정렬만 적용하며, 검색어에서 조건을 추출하지 않는다.

입력

{
  "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
}

출력 200

{
  "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
  }
}

0건 응답. 대화형 추천으로 전환할 수 있다는 신호를 함께 반환한다. 서버는 전환을 수행하지 않는다.

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

에러

¹ 키워드 검색이 실패하면(AI Postgres 장애 등) 벡터 결과와 상관없이 500. BE MySQL 장애는 해당하지 않는다

² 키워드 검색 결과만 반환한다. 임베딩 업스트림 장애, 벡터 인덱스 이상, 초기 적재 중일 때 나온다. 복제 지연·행 부재는 해당하지 않는다

• popular(인기순)은 v_book_popularity의 최근 판매 수로 산출한다(MVP, BE #68 합의). 챗봇의 후보 채점, 피드의 인기 항, cold_start 목록도 같은 테이블을 읽는다. 리뷰까지 반영한 공식은 BE가 복제 칼럼으로 주면 그때 반영한다.
• 검색은 개인화하지 않으므로 사용자 이력(구매, 도서관, 리뷰)을 읽지 않는다. 누가 검색하든 같은 순위다. 인기는 사용자와 무관한 도서 단위 값이라 이 원칙을 깨지 않는다.

텍스트를 벡터로 변환한다. 내부 전용이며 검색어와 도서 정보 모두 이 API를 쓴다. 한 번에 최대 256건이므로 대량 적재는 나눠서 호출한다.

벡터 길이는 응답의 dim으로 알려준다. 호출자는 이 값이 자신이 쓰는 벡터 인덱스의 차원과 같은지 확인한 뒤 저장해야 한다.

벡터는 multilingual-e5-small 384차원이다(ERD §5).

초기 적재

서비스 시작 시점과 임베딩 모델 교체 시점에 카탈로그 전체의 벡터를 한 번에 만든다.

1. BE 카탈로그가 v_books로 전량 복제된다. 복제가 끝나기 전에는 임베딩을 만들지 않는다 — 대상 목록이 확정되지 않는다.
2. description이 있는 행을 book_id 순으로 256건씩 나눠 호출한다. 카탈로그 N권이면 ceil(N / 256)회.
3. 응답의 dim을 확인한 뒤 book_embeddings에 upsert한다. description이 없는 도서는 벡터 검색 대상에서 빠지고 키워드 검색으로만 조회된다.
4. 중단되면 행이 없는 book_id부터 다시 시작한다. upsert라 중복 실행이 결과를 바꾸지 않는다.

적재 중에도 검색은 응답한다. 벡터 결과가 부족한 동안 X-Degraded: keyword-only가 나가며, 이는 임베딩 장애 때와 같은 상태라 BE가 추가로 할 일은 없다. 신간도 복제 후 같은 절차를 타며, 두 단계를 합친 허용 지연은 ERD §3의 신선도 예산을 따른다.

입력

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

¹ 넘는 부분은 오류 없이 잘린다. 512토큰은 한글로 약 640자다

² 기본 document. 용도에 따라 벡터를 다르게 만들기 때문에 구분

출력 200

{
  "message": "embed_success",
  "data": {
    "vectors": [[0.0123, -0.0456, "…"]],
    "dim": 384,
    "model": "multilingual-e5-small"
  }
}

에러

사용자 메시지로 추천 조건(spec)을 갱신하고 그 조건으로 도서를 조회한다. 갱신된 조건, 추천 카드 최대 3장, 답변 문장을 함께 반환한다.

카드의 한 줄 이유(reason_short)와 상세 페이지용 긴 이유(reason_long)를 한 번의 LLM 호출로 함께 만든다. 상세 페이지를 열 때 이유를 다시 생성하는 별도 엔드포인트는 두지 않는다. 카드를 고른 근거와 이유 문장이 같은 호출에서 나오므로 둘이 어긋나지 않고, 상세 진입에 LLM 지연이 없으며, 이유 캐시 테이블과 그 만료, 권한 규칙이 통째로 사라진다. 대신 사용자가 열어 보지 않는 카드의 긴 이유도 만들게 되어 턴당 출력 토큰이 늘어난다. 긴 이유의 보관은 BE 몫이다 — 카드와 함께 받아 두었다가 상세 페이지에서 그대로 쓴다.

(V2) image_ref가 있으면 이미지 요청으로 처리한다. message와 배타이며, 표지를 인식해 recognition을 채우고 spec.anchor_book을 갱신한다. 인식 전용 엔드포인트는 두지 않는다.

서버는 대화를 저장하지 않는다. V1에서는 호출자가 spec과 최근 대화를 요청마다 실어 보낸다. V2에서는 백엔드가 대화 스레드를 보관한다.

추천과 쇼핑을 가르는 일은 AI 서버가 한다. idempotency_key가 있는 요청이면 AI 서버의 규칙(LLM을 부르지 않는다)이 말 한 줄과 카드가 보이는지를 보고 갈래를 정한다. 추천 낱말만 있으면 ③이 바로 처리하고(route: "recommend"), 그 밖의 말은 ⑦이 처리한다(route: "shop"). ⑦이 쇼핑 요청이 아니라고(not_shopping) 하면 같은 요청을 ③이 처리한다. 이 되돌림은 BE에 보이지 않는다. ⑦이 실패하면 ③의 추천으로 덮지 않고 그 에러를 그대로 돌려준다. 장바구니 요청에 추천 답을 하는 쪽이 더 나쁘기 때문이다. idempotency_key가 없으면 규칙을 쓰지 않고 ③만 처리하며 응답에 route도 없다.

처리(참고)

1. 이번 메시지로 spec을 갱신한다. LLM이 한다
2. 갱신된 spec으로 후보 10권을 뽑는다. 키워드와 벡터 순위를 합치고 취향 유사도로 점수를 매긴다. 취향은 취향 프로필에 프로필이 반영한 이력 이후에 생긴 이력(구매, 담기, 리뷰)을 더한 것이고, 인기는 v_book_popularity에서 읽는다. 산 책과 나의 도서관 책은 후보에서 뺀다. 요청에 purchased_isbns, library_isbns가 오지 않으면 복제 테이블에서 산 책과 별점 1–2점을 준 책을 뺀다
3. LLM이 후보 중 3권을 고르고 카드마다 한 줄 이유(reason_short), 긴 이유(reason_long), 근거(match_basis)를 한 번의 호출로 쓴다. 고른 순서가 곧 rank이며,
   match_score는 후보 점수 그대로라 내림차순이 아닐 수 있다
4. 한 줄 이유를 못 만든 책은 뺀다. 그래서 3장보다 적을 수 있다. 긴 이유만 비면 카드는 남기고 reason_long: null로 둔다(BE는 상세 페이지의 이유 영역을 숨긴다)

LLM 장애면 1과 3을 건너뛰고 요청의 spec으로 2만 돌려 점수 상위 3권을 낸다. degraded: true. 이때 reason_short는 규칙으로 만들고 reason_long은 null이다

입력

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

¹ 서버가 대화를 저장하지 않으므로 클라이언트가 직전 응답의 spec을 그대로 돌려보내야 대화가 이어짐(V2는 BE가 보관). 첫 턴은 초기 spec

² 1–200자. 텍스트 턴에는 필수, 이미지 턴(image_ref 있음)에는 보내지 않음

³ 서버가 대화를 기억하지 않아 매 턴 같이 보냄. 최대 20턴(초과분은 최근 20턴만 사용), text 각 200자 이하

⁴ 1장, JPG, PNG, 10MB 이하. 있으면 이미지 턴이 됨

⁵ V1에서는 동작에 영향 없음. 개인화는 취향 프로필 유무로 판단한다(AI #266). V2에서 false면 대화에서 취향을 뽑지 않는다

⁶ 책 번호를 ISBN으로 옮기는 중이라 두 칸을 다 받는다(AI #317). 다 옮기면 exclude_book_ids를 뺀다. ISBN은 13자리 숫자 문자열이고 형식이 틀리면 400이다. 책 표에 없는 ISBN은 건너뛴다

⁷ BE가 요청마다 싣는다(AI #319). 칸이 없거나 null인 것과 빈 목록 []은 뜻이 다르다. 두 칸이 모두 없거나 null이면 아직 보내지 않는 것으로 보고 복제 테이블의 이력으로 뺀다. 빈 목록은 가진 책이 없다는 뜻이라 복제 테이블을 읽지 않는다. 그래서 목록을 채우기 전에 []부터 보내면 산 책이 다시 추천된다. 별점 1–2점을 준 책은 따로 받지 않는다. 리뷰는 산 책에만 달 수 있어 산 책 목록에 들어 있다. 형식과 책 표에 없는 ISBN은 ⁶과 같다. 목록 개수 상한은 아직 정하지 않았다(BE #252). 요청 본문은 64KB까지이고 넘으면 413이다

⁸ 쇼핑 칸은 모두 선택이다. idempotency_key가 있으면 규칙을 켜고, 없으면 이 변경 전과 같이 ③만 처리하며 응답 모양도 같다(BE가 쇼핑 칸을 보내기 전에 AI 서버가 먼저 배포되어도 안전하다). 쇼핑 칸은 갈래가 shop일 때만 ⑦ 입력 검사로 검사하고 틀리면 400이다. 갈래가 recommend면 검사하지 않아 ③이 쇼핑 칸 때문에 실패하지 않는다. idempotency_key는 요청마다 새 값을 쓰고, 같은 요청을 다시 보낼 때만 같은 값을 쓴다. 재시도에서 spec 같은 본문이 달라지면 새 값을 쓴다. 쇼핑 갈래는 한 턴이 최대 30초라서 BE의 읽기 제한 시간은 이보다 길어야 한다. ③ 칸(user_id, message, recent_turns)은 ⑦도 같은 값을 쓴다. ③ 칸 검사(spec 등)는 갈래와 상관없이 먼저 한다

spec 스키마. 서버가 이 형식을 검증한다.

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

6개 키는 요청, 응답 모두 항상 존재한다. 빈 값은 null, {}, []로 채운다. 아래 초기 spec이 그 기본형이다.

anchor_book과 exclude는 ISBN으로 옮기지 않고 도서 ID 그대로 둔다. AI가 만들어 응답에 싣고 호출자가 다음 요청에 그대로 되돌려 보내는 값이라 BE가 해석하지 않는다(AI #317).

초기 spec. 새 스레드의 첫 턴, 그리고 422 이후 초기화할 때 BE가 보내는 값이다.

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

출력 (200). 일반 추천 턴

{
  "message": "recommend_success",
  "data": {
    "reply": "비 오는 날 분위기에 맞춰 골라봤어요.",
    "spec": { "…": "갱신된 추천 조건(6키 전체)" },
    "recognition": null,
    "cards": [
      {
        "book_id": 1088,
        "isbn": "9788900000011",
        "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
  }
}

buttons, degraded는 V1 일반 턴에도 항상 존재한다. 일반 턴은 보통 buttons: [], degraded: false.

출력 (200). 쇼핑 칸을 보낸 요청 (V2)

idempotency_key를 보낸 요청의 응답에는 data.route가 있다. 안 보낸 요청에는 route가 없다.

shop이면 spec, cards, followup, degraded는 오지 않는다. BE는 카드를 저장하지 않고, 저장해 둔 spec을 바꾸지 않는다. 버튼은 객체 목록이며 action 값은 5장 표를 따른다.

{
  "message": "agent_success",
  "data": {
    "route": "shop",
    "reply": "《달러구트 꿈 백화점》을 장바구니에 담았어요.",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "cart.add",
        "arguments": { "isbn": "9788900000011", "quantity": 1 },
        "result": { "ok": true },
        "grounded": true
      }
    ],
    "resolved_reference": { "ref": "1번", "isbns": ["9788900000011"] },
    "selection": null,
    "buttons": [
      { "label": "장바구니 보기", "action": "navigate", "target": "CART-001" }
    ]
  }
}

출력 (200). 이미지 턴 (image_ref 있음) (V2)

표지를 한 권으로 특정한 경우. 도서 소개 문장, 유사 도서 카드, 후속 동작 목록을 함께 반환한다.

{
  "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
  }
}

인식 후보가 여럿인 경우. 확정하지 않고 후보를 최대 3개 제시해 사용자가 고르게 한다.

{
  "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
  }
}

인식 실패면 200에 candidates: []와 안내 reply로 응답한다.

¹ 한 줄 이유를 못 만든 책은 뺌(긴 이유만 비면 카드는 남고 reason_long이 null). 이미지 턴은 책이 매칭된 경우(recognized: true)에만 채우고 그 외 []

² 이번 요청 조건(spec.semantic) 유사도와 취향 유사도(취향 프로필 + 프로필 이후의 이력)를 함께 쓴다. 개인화 추천 목록의 점수와 계산식이 다르다

³ reason_short와 같은 LLM 호출에서 같은 근거로 만든다. 못 만들면 null(degraded일 때 포함)

⁴ 항목: book_id, title, author, cover_url, confidence(0–1, 내부 판정용). 그 외 []

⁵ 책 번호를 ISBN으로 옮기는 중이라 book_id와 함께 싣는다(AI #317). 다 옮기면 book_id를 뺀다

• 긴 이유는 이 응답이 마지막 생성 지점이다. AI 서버는 카드를 캐시하지 않으므로, BE가 reason_long을 카드와 함께 보관했다가 상세 페이지에서 그대로 보여준다. 같은 책을 다시 상세로 열어도 AI를 부르지 않는다.
• 두 이유는 같은 근거(match_basis)에서 나온다. 한 줄 이유는 카드 한 줄, 긴 이유는 그 근거를 질의와 취향에 붙여 2–4문장으로 푼 것이다.
• 가진 책은 요청으로 받고, 인기는 요청에 담기지 않는다. 산 책과 나의 도서관 책은 BE가 purchased_isbns, library_isbns로 싣는다(입력 ⁷). 두 칸이 오지 않는 동안은 서버가 user_id로 v_user_purchases, v_user_library, v_user_reviews를 복제 테이블에서 읽는다. 인기는 book_id로 v_book_popularity를 복제 테이블에서 읽는다. 복제 지연만큼 값이 늦게 반영될 수 있으며 그건 오류가 아니다(ERD §3 신선도 예산).
• 표지를 읽지 못한 경우와 읽었으나 카탈로그에 없는 경우를 구분하지 않는다. 두 경우 모두 같은 안내 reply를 반환한다.

에러

취향 프로필로 개인화 추천 목록을 만든다. 검색어를 받지 않는다. 점수는 규칙 기반 점수(작가, 카테고리, 태그, 이력, 인기)와 취향 벡터 유사도의 가중합이며 LLM을 호출하지 않는다.

규칙 점수의 두 항은 각각 출처가 있다. 이력은 v_user_purchases, v_user_library, v_user_reviews를 user_id로 읽은 것이고, 인기는 v_book_popularity(최근 판매 수, MVP는 판매 수 단일 기준)다. 둘 다 요청에 담기지 않고 서버가 복제 테이블에서 읽는다. 행이 없는 도서는 인기 항 0점으로 계산한다. 유사도 항(0.6)을 빼는 rule-only 응답은 남은 비중(카테고리 0.25+인기 0.15)을 1로 재분배하지 않아 최대 40점이다(축소 응답도 같은 잣대라는 원칙).

개인화가 없는 판매량 순위 목록은 이 API의 범위가 아니다.

서버는 결과 목록을 보관하지 않는다. 커서는 이어 붙일 위치만 담으며 같은 순서의 재현을 보장하지 않는다. 프로필이나 인기 집계가 바뀌면 갱신된 값으로 이어 붙인다. 커서 발급 이후에 생긴 조회, 구매 이력은 제외 대상에서 뺀다.

입력

쿼리 파라미터로 받는다. 요청 본문은 없다.

# 첫 요청 또는 정렬, 필터를 바꿔 처음부터 다시 조회. cursor 없음
GET /recommendations/feed?user_id=123&surface=home&size=15

# 이어서 조회. 직전 응답의 next_cursor를 그대로 싣는다(값은 URL 인코딩)
GET /recommendations/feed?user_id=123&surface=recommend_more&sort=match
    &category=에세이&pub_year_from=2020&match_score_min=70&size=15&cursor=eyJ…

¹ match(기본), newest, price_asc. surface가 recommend_more일 때만 유효

• 위 아홉 개가 허용 파라미터 전부이며, 그 밖의 키가 오면 400이다. 정렬(sort)과 필터 세 종류(category, 출간연도 구간, match_score_min)는 surface가 recommend_more일 때만 유효하고, home에 오면 400이다.
• 값은 URL 인코딩해서 싣는다. 특히 cursor는 서버가 서명한 문자열이라 +·/·=가 섞이고, category는 한글이다.

출력 200

{
  "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
  }
}

• 피드 항목에는 추천 이유 문구가 없다. 순서와 match_score만 낸다. 이유는 대화형 추천 카드에서만 나온다(③의 reason_short·reason_long). 피드가 LLM을 호출하지 않는다는 원칙을 지키기 위해서다.
• 커서 제외 규칙의 ’조회, 구매 이력’은 v_user_purchases, v_user_library를 말한다. 이미 산 책과 담은 책, 별점 1–2점을 준 책은 목록에서 빼되, 커서 발급 이후에 생긴 것은 제외 대상에서 뺀다(카드를 보고 돌아와 스크롤해도 목록이 밀리지 않게).
• 카탈로그에서 사라진 도서(삭제·비공개)는 v_books 조인에서 빠지므로 한 페이지가 size보다 짧을 수 있다. 짧은 페이지는 목록의 끝이 아니며, 끝은 next_cursor: null로만 판정한다.
• 필터 없이 후보가 0건인 경우는 없다. 필터로 0건이면 items: [], next_cursor: null로 200을 돌려준다. 에러가 아니며 필터를 임의로 풀지 않는다.
• 응답에 Cache-Control: private, no-store를 붙인다. 개인화 목록인 데다 서버가 결과를 보관하지 않아 같은 URL이라도 호출할 때마다 본문이 달라진다. 중간 캐시가 응답을 재사용하면 남의 목록이 다른 사용자에게 나갈 수 있다.

에러

¹ 취향 유사도를 빼고 규칙 기반 점수만으로 정렬한다. 남은 비중을 1로 재분배하지 않아 match_score는 최대 40점이다. 벡터 인덱스 이상과 모델 교체 구간에만 나온다. centroid가 없으면 이 값이 아니라 cold_start: true이고, 복제 지연·행 부재도 해당하지 않는다

야간 배치가 그날 활동이 있었던(종료된) 대화 세션을 모아 세션 단위로 호출한다. 세션의 메시지 전체를 LLM에 넣어 취향 사실을 뽑고, 각 사실을 임베딩해 벡터와 함께 돌려준다. 저장은 BE가 한다(취향 테이블에 한 행씩). AI 서버는 입력도 결과도 저장하지 않으며 AI DB에도 남기지 않는다. 뽑은 기억이 AI로 되돌아오는 경로는 ⑥ 요청 본문 하나뿐이다.

뽑는 기준

• 사용자가 자기가 읽으려고 찾거나 좋아한다고 말한 분위기, 주제, 작가, 늘 지키는 쪽수·가격·출간연도 조건을 뽑는다. 좋아한다고 직접 말하지 않고 추천을 부탁하기만 해도 뽑는다.
• 싫어하거나 읽지 않는다고 말한 것도 뽑는다.
• 이미 저장된 취향인지는 보지 않는다. 같은 취향을 다른 날 또 말하면 또 뽑는다.
• 남에게 줄 책, 제목으로 찾은 책 한 권은 뽑지 않는다. 배송이나 번역서·오디오북처럼 책 정보로 가를 수 없는 조건도 뽑지 않는다.
• "오늘은", "이번 달은"처럼 이번만이라고 밝힌 것과 말했다가 거둔 것은 뽑지 않는다.
• 챗봇만 말하고 사용자가 받아들이지 않은 것은 뽑지 않는다.
• 좋아한 책을 제목으로만 말하면 topic으로 뽑고 문장에 그 제목을 넣는다. 사용자가 말하지 않은 그 책의 성격은 덧붙이지 않는다.
• 병명, 소송, 가족의 사정 같은 민감한 개인사는 문장에 넣지 않는다.

입력

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

출력 200

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

¹ 양수는 좋아함, 음수는 싫어함이다. 크기는 추천을 부탁하기만 했으면 1, 직접 말했으면 2, 강하게 말했으면 3이다. 싫은 쪽을 부탁하기만 한 것(-1)은 내지 않는다

² ②의 purpose: query와 같은 방식으로 만든다. 책 벡터와 견주는 쪽이기 때문이다

³ topic일 때만 채우고, 맞는 것이 없거나 다른 종류면 []이다. 이름은 온보딩 3·4번 보기와 같고, AI 서버만 쓰는 세부 카테고리도 올 수 있다. BE는 검사하지 않고 저장했다가 ⑥에 그대로 보낸다

⁴ 주제는 그 주제("추리 소설"), 작가는 이름("김영하"), 분위기는 그 말("잔잔한"), 조건은 정해진 꼴("300쪽 이하", "1만 원 이하", "2024년 이후")이다. 책 제목만 말했으면 『』로 감싼다("『불편한 편의점』")

에러

온보딩 응답과 취향 기억으로 취향 프로필(취향 벡터와 태그 가중치)을 만들어 저장한다. 개인화를 쓰는 모든 API가 이 프로필을 참조한다.

구매, 나의 도서관, 리뷰는 요청으로 받지 않는다. 서버가 user_id로 복제 테이블 v_user_purchases, v_user_library, v_user_reviews를 읽어 계산에 넣는다. 호출자가 이력을 모아 보낼 필요가 없다. 복제 직전에 생긴 이력은 이번 계산에서 빠질 수 있으나 결과에서 누락되지는 않는다 — 아래 computed_at 설명 참고.

호출 시점은 온보딩 완료 직후와 취향 기억이 바뀔 때 둘뿐이다. BE는 개인화 추천에 동의한 사용자만 부른다. 프로필이 없는 사용자는 구매·리뷰 이력이 있어도 ③④가 개인화하지 않는다(AI #266). 구매나 리뷰가 늘었다고 다시 부르지 않아도 된다 — 프로필이 반영한 이력 이후에 생긴 이력은 ③, ④가 채점할 때 그 자리에서 읽어 더한다(아래 처리 참고).

호출할 때마다 전체를 다시 계산한다. 취향 기억을 지웠을 때 그 몫만 분리해 뺄 수 없기 때문이다.

동시 호출은 user_id 단위로 직렬 처리하며 나중에 끝난 요청의 결과가 남는다.

이 경로는 LLM과 임베딩을 호출하지 않으므로 503, 504가 없다.

입력

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

¹ 같은 키, 같은 본문이면 다시 계산하지 않고 저장 결과를 200으로 반환. 응답이 유실돼 재시도해도 프로필이 두 번 바뀌지 않게

² 매번 처음부터 다시 만들기 때문에 기억만 바뀌어도 온보딩 응답을 다시 보냄. 건너뛴 사용자는 {}

³ 매번 전체를 보내 처음부터 다시 계산. 작가 취향은 이 경로로만 들어옴(type: author). 최대 500건(넘으면 created_at이 최근인 500건만). 보내는 순서는 상관없다

⁴ 서버가 모르는 이름이면 그 이름만 건너뛰고 400이 아니다

⁵ 날짜·시각(한국 시간). 예: 2026-09-04T00:12:30.123456. 소수점 아래는 없어도 된다. 같은 관심사를 좋아한다고도 싫다고도 했을 때 어느 쪽이 나중인지 가리는 데 쓴다. 같은 밤에 저장된 줄끼리도 가려야 해서 마이크로초까지 보낸다

• memories[].dim이 서버가 쓰는 벡터 인덱스 차원과 다르면 400 invalid_request로 거절한다.
• memories[]의 strength가 범위 밖이거나 0, applies_to가 4개 이상, keyword가 비었거나 100자를 넘음, created_at이 날짜·시각 모양이 아니면 400 invalid_request로 거절한다.
• 이력은 요청 필드가 아니라 복제 테이블에서 읽으므로, 같은 idempotency_key에 같은 본문이어도 그 사이 구매가 생겼거나 복제가 도착하면 결과가 달라질 수 있다. 멱등 규약은 재계산을 건너뛰고 저장된 결과를 그대로 돌려주는 것이라 이 경우에도 응답은 일관된다.

출력 200

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

처리(참고)

이력 = v_user_purchases ∪ v_user_library ∪ v_user_reviews  (복제 테이블, user_id로 조회)

centroid = 가중평균( liked 책 문서벡터
                   ∪ 카테고리, 태그 사전임베딩 벡터 ∪ memories[].vector
                   ∪ 이력 책들의 문서벡터(구매 3, 리뷰 4~5점 2, 담기 1) )
태그 가중치 = 온보딩 태그 + 기억 type 집계(V1 미구현) + 이력 책들의 카테고리 점수
→ {centroid, tag_weights, cold_start, computed_at} 을 취향 프로필 테이블에 upsert
   (computed_at = 위에서 실제로 읽은 이력 행들의 시각 중 최댓값. 계산 시각이 아니다)

이력 가중치. 카테고리 점수와 centroid 가중평균에 같은 값을 쓴다.

¹ 2.0점 이하. centroid 재료에서는 빼고(가중평균에 넣지 않는다) 그 책 자체는 추천에서 제외한다. 카테고리 점수는 책마다 큰 값 하나라, 산 책이면 구매 점수가 남는다(AI #103)

• 같은 책이 여러 테이블에 있으면(구매한 책에 리뷰까지 쓴 경우) 가장 큰 가중치 하나만 쓴다. 더하지 않는다.
• 취향 기억은 좋아함 줄만 centroid에 섞는다. 세기가 양수이고 조건이 아니며, 그 뒤에 같은 관심사를 피한다고 하지 않은 줄이다. 핵심어 벡터에는 좋고 싫음이 담기지 않기 때문이다(AI #395).
• 이력이 하나도 없고 온보딩도 건너뛰었으면 cold_start: true다. 구매나 리뷰가 하나라도 있으면 개인화를 켠다.
• computed_at은 응답에 나가지 않는 내부 값이다. 프로필이 실제로 반영한 이력 행들의 최대 시각을 저장해 두고, ③·④가 채점할 때 그보다 나중의 이력만 골라 점수에 더한다(같은 가중치 표). 프로필을 다시 만들지 않아도 방금 산 책이 다음 추천에 반영되고, 이미 녹아든 이력을 두 번 더하지 않는다. 보정은 AI 서버 안에서 끝나 호출자가 할 일은 없다.
• 계산 시각이 아니라 반영 시각이어야 한다. 이력을 복제 테이블에서 읽으므로 계산 시점에 아직 도착하지 않은 이력이 있을 수 있는데, 계산 시각을 기준으로 삼으면 그 이력이 프로필에도 가산 대상에도 없어 영구히 누락된다. 반영한 이력이 없으면 값이 비고 그때는 이력 전부를 가산한다.

에러

대화 중에 나온 쇼핑 요청(“담아줘”, “빼줘”, “3만원 안에서 골라줘”, “재고 있어?”, “1번이랑 3번 뭐 달라”, “배송 언제?”)을 알아듣고 백엔드 기능(tool)을 대신 실행한다. 서버에 대화를 저장하지 않는다. 대화 맥락은 요청에 담겨 온다. 주문 생성, 결제는 범위 밖이며 결제 화면으로의 이동만 안내한다.

다루는 요청: 시키는 대로 실행(담기, 수량 변경, 빼기, 장바구니 조회, 주문 요약, 재고), 조건 걸고 골라 담기(예산, 권수 안에서 조합을 골라 줌. 가능한 조합을 전부 따져 본다), 비교, 배송 문의(안내와 이동 버튼), “이거, 1번”이 어느 책인지 찾기 + 애매하면 되묻기. 주문 요약은 장바구니 조회 결과로 답한다. 제외: ‘제일 취향인 거’, 선물 의도, 단건 Q&A, 취소, 환불, 결제수단, 결제 확정, 실시간 배송 추적, 무료배송 조건, 웹 검색, 리뷰.

호출 경로. BE는 이 엔드포인트를 직접 부르지 않고 ③ 챗봇 입구에 쇼핑 칸을 실어 보낸다(③ 입력 ⁸). AI 서버가 추천인지 쇼핑인지 가려 이 처리로 넘긴다. 이 엔드포인트는 같은 처리를 직접 부르는 입구로 그대로 남고, 직접 부르면 not_shopping: true가 그대로 나간다.

입력

{
  "user_id": 123,
  "conversation_id": "cv_…",
  "message": "2만 7천원 안에서 2권 골라 담아줘",
  "context_cards": [
    { "isbn": "9788900000011", "rank": 1, "match_score": 92 },
    { "isbn": "9788900000028", "rank": 2, "match_score": 87 },
    { "isbn": "9788900000035", "rank": 3, "match_score": 81 }
  ],
  "focused_isbn": "9788900000011",
  "user_context": { "logged_in": true },
  "allow_tools": null,
  "idempotency_key": "idem_…"
}

¹ “1번, 이거” 같은 지시 표현을 풀고 후보를 고르는 재료. 호출자는 사용자 화면에서 가장 최근에 카드가 보인 묶음을 보낸다. 그 뒤에 카드가 없는 턴(⑦ 등)이 끼어도 마지막으로 보인 묶음을 유지하고, 보인 카드가 없으면 빈 배열이거나 생략한다. 항목: isbn, rank, match_score. 최대 10개, 초과는 400. 카드의 가격과 재고는 받지 않는다. 가격, 재고는 이번 턴의 tool 결과로만 말한다

² 재시도로 같은 요청이 두 번 와도 장바구니에 두 번 담기지 않게. 읽기만 하는 턴에서는 무시. BE로는 이 키에서 파생한 키를 보내지 않는다. 담기와 수량 변경이 요청 수량으로 바꾸는 방식이라 같은 호출을 두 번 보내도 결과가 같다

³ “1번이요”, “네”처럼 되물은 다음 턴의 답을 직전 말과 이어서 푸는 재료다. ③의 recent_turns와 같은 모양이고, 최대 20턴(초과분은 최근 20턴만 쓴다), 한 줄 text는 200자다. 200자를 넘는 줄은 400이 아니라 뒤쪽 200자만 쓴다(구현 예정, 지금은 400). 제안과 질문이 말의 끝에 오기 때문이다. 항목 길이 위반을 400으로 하는 5장 ‘상한 초과 처리’의 예외다. ⑦의 답변에는 길이 상한이 없어서 호출자가 그대로 싣으면 200자를 넘을 수 있다

출력 200

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》 + 《아무튼, 산》 = 26,300원. 이 둘 담을까요?",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "book.offer",
        "arguments": {
          "isbns": ["9788900000011", "9788900000028", "9788900000035"]
        },
        "result": {
          "offers": [
            { "isbn": "9788900000011", "title": "달러구트 꿈 백화점", "price": 13500, "in_stock": true },
            { "isbn": "9788900000028", "title": "밤의 도서관", "price": 14000, "in_stock": true },
            { "isbn": "9788900000035", "title": "아무튼, 산", "price": 12800, "in_stock": true }
          ]
        },
        "grounded": true
      },
      {
        "name": "selection.pick",
        "arguments": { "budget_total": 27000, "count": 2 },
        "result": {
          "ok": true,
          "chosen": [
            { "isbn": "9788900000011", "title": "달러구트 꿈 백화점", "price": 13500, "match_score": 92 },
            { "isbn": "9788900000035", "title": "아무튼, 산", "price": 12800, "match_score": 81 }
          ],
          "total_price": 26300,
          "alternatives_considered": 3
        },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "2만 7천원 2권",
      "isbns": ["9788900000011", "9788900000035"]
    },
    "selection": {
      "goal": "budget_pick",
      "constraints": { "budget_total": 27000, "count": 2 },
      "chosen": [
        { "isbn": "9788900000011", "price": 13500, "match_score": 92 },
        { "isbn": "9788900000035", "price": 12800, "match_score": 81 }
      ],
      "total_price": 26300,
      "alternatives_considered": 3
    },
    "buttons": [
      {
        "label": "담기",
        "action": "confirm_selection",
        "isbns": ["9788900000011", "9788900000035"]
      }
    ]
  }
}

¹ 없으면 []. 골라 담기, 비교, 화면 안내처럼 AI 서버 안에서 처리한 tool도 기록용으로 포함

² BE tool의 결과 형식은 예시이며 BE와 합의해 확정

³ 사용자의 말이 가리킨 책(번호, 그 책만 가리키는 제목 낱말, 지금 보고 있는 책)이 정해질 때만 isbns를 채운다. 어느 책인지 하나로 정해지지 않으면 null이고 되묻는 답변을 준다. 되묻기 위해 선택지의 제목을 조회(book.offer)했어도 그 책들은 싣지 않는다. 그래서 되물음의 tool_calls는 []이거나 조회 기록만 있다

⁴ 지금 만드는 버튼은 confirm_selection과 navigate뿐이다. confirm_reference, dismiss, reselect, open_book은 5장 action 표에 정의만 있고 만들지 않는다(후속). 버튼 없이 되물으면 buttons는 []다. confirm_selection을 눌렀을 때 누가 담는지는 5장 action 표 아래 설명을 따른다

grounding 규칙

1. 답변에 담긴 수치, 상태(가격, 재고, 수량, 합계)는 반드시 이번 턴 tool_calls[].result에서만 주입한다. 직전 카드에 있던 값은 쓰지 않는다.
2. 특정 수치를 뒷받침한 tool 결과가 없으면 → 그 tool_call의 grounded: false로 기록하고, 가능하면 해당 문장만 축약, 제거해 200으로 응답한다.
3. 줄여도 답변의 핵심 주장(사용자가 요청한 행동의 결과)이 근거 미확보로 남으면 → 답변 전체를 버리고 422 grounding_failed. 클라이언트는 답변을 표시하지 않고 일반 안내로 대체한다.
4. 되물음(어느 책인지 정해지지 않음), 범위 밖 안내, 쇼핑 요청 아님, BE tool 실패 흡수는 모두 200이다(답변으로 안내, tool_calls에 실패 기록).
5. 행동 서술(“담았어요”, “뺐어요”, “바꿨어요”)은 해당 쓰기 tool이 성공했을 때만 남긴다. 실행하지 않았거나 실패했으면 그 문장을 지우고 사실대로 쓴다. 지워도 핵심 주장이 거짓으로 남으면 3번처럼 422다.

출력 예시. 유형별

시키는 대로 실행, 담기

담기 전에 BE에서 장바구니를 다시 읽는다. 담기가 “요청 수량으로 바꾸기”라서 이미 담긴 책을 담으면 수량이 줄 수 있기 때문이다. 이 조회는 cart.add 안에서 하며 tool_calls에 따로 남지 않는다.

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》을 장바구니에 담았어요.",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "cart.add",
        "arguments": { "isbn": "9788900000011", "quantity": 1 },
        "result": { "ok": true },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "1번",
      "isbns": ["9788900000011"]
    },
    "selection": null,
    "buttons": [
      { "label": "장바구니 보기", "action": "navigate", "target": "CART-001" }
    ]
  }
}

이미 담긴 책 (담지 않고 알림)

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》은 이미 장바구니에 2권 담겨 있어요. 수량을 바꾸시려면 알려 주세요.",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "cart.add",
        "arguments": { "isbn": "9788900000011", "quantity": 1 },
        "result": {
          "ok": false,
          "error": "ALREADY_IN_CART",
          "title": "달러구트 꿈 백화점",
          "quantity": 2
        },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "1번",
      "isbns": ["9788900000011"]
    },
    "selection": null,
    "buttons": [
      { "label": "장바구니 보기", "action": "navigate", "target": "CART-001" }
    ]
  }
}

장바구니 보기, 합계

cart.view 결과의 total은 AI 서버가 구매할 수 있는 책의 가격 × 수량을 더해 넣는다. BE는 합계를 주지 않는다. 합계는 이 값으로만 말한다.

{
  "message": "agent_success",
  "data": {
    "reply": "《달러구트 꿈 백화점》 2권과 《아무튼, 산》 1권이 담겨 있고, 합계는 39,800원이에요.",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "cart.view",
        "arguments": {},
        "result": {
          "items": [
            {
              "isbn": "9788900000011",
              "title": "달러구트 꿈 백화점",
              "price": 13500,
              "quantity": 2,
              "available": true
            },
            {
              "isbn": "9788900000035",
              "title": "아무튼, 산",
              "price": 12800,
              "quantity": 1,
              "available": true
            }
          ],
          "total": 39800
        },
        "grounded": true
      }
    ],
    "resolved_reference": null,
    "selection": null,
    "buttons": [
      { "label": "장바구니 보기", "action": "navigate", "target": "CART-001" }
    ]
  }
}

되물음 (tool 미실행)

카드와 장바구니 목록에 대조해도 어느 책인지 하나로 정해지지 않을 때가 이 경우다. 사용자의 말에 책을 가리키는 번호, 제목, “전부” 같은 근거가 없는데 LLM이 책을 골라 쓰기 tool을 부르려 하면 코드가 REFERENCE_NOT_STATED로 막고 되묻게 한다. 되묻기 버튼(네, 1번, 아니요)은 아직 만들지 않는다.

{
  "message": "agent_success",
  "data": {
    "reply": "어떤 책 말씀이실까요? 방금 추천한 1번 《달러구트 꿈 백화점》이 맞을까요?",
    "not_shopping": false,
    "tool_calls": [],
    "resolved_reference": null,
    "selection": null,
    "buttons": []
  }
}

비교 (book.offer로 가격을 읽고 book.compare로 소개글의 차이를 설명)

{
  "message": "agent_success",
  "data": {
    "reply": "1번은 문장이 담백해 부담이 적고, 3번은 화제작인데 호흡이 무거워요. 가격은 700원 차이(1번 13,500 / 3번 12,800)예요.",
    "not_shopping": false,
    "tool_calls": [
      {
        "name": "book.offer",
        "arguments": { "isbns": ["9788900000011", "9788900000035"] },
        "result": {
          "offers": [
            { "isbn": "9788900000011", "title": "달러구트 꿈 백화점", "price": 13500, "in_stock": true },
            { "isbn": "9788900000035", "title": "아무튼, 산", "price": 12800, "in_stock": true }
          ]
        },
        "grounded": true
      },
      {
        "name": "book.compare",
        "arguments": { "isbns": ["9788900000011", "9788900000035"] },
        "result": {
          "ok": true,
          "basis": "description",
          "summary": "1번은 문장이 담백하고 3번은 화제작이지만 호흡이 무겁다."
        },
        "grounded": true
      }
    ],
    "resolved_reference": {
      "ref": "1번, 3번",
      "isbns": ["9788900000011", "9788900000035"]
    },
    "selection": null,
    "buttons": []
  }
}

배송 문의, 범위 밖 (tool 없음, 딥링크)

BE tool은 쓰지 않고, AI 서버 안의 ui.guide로 이동 버튼만 붙인다.

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

쇼핑 요청이 아님

{
  "message": "agent_success",
  "data": {
    "reply": "",
    "not_shopping": true,
    "tool_calls": [],
    "resolved_reference": null,
    "selection": null,
    "buttons": []
  }
}

에러

내부 처리 (요청 1건에 끝남)

1. 입력 검사와 중복 확인. 형식을 검사하고, 같은 idempotency_key가 이미 처리됐으면 저장된 결과를 돌려준다. 쇼핑 요청이 아니면 not_shopping: true로 끝낸다. ③ 입구로 들어온 요청이면 같은 요청을 ③이 이어 받는다.
2. tool 반복. 시작할 때 로그인한 요청이면 코드가 장바구니를 먼저 읽어, 번호 붙은 목록(번호, 제목, 수량)을 LLM에게 보여 준다. 가격과 합계는 보여 주지 않아서 cart.view 결과로만 말한다. 읽지 못하면 건너뛴다. 상한 3번. LLM이 tool을 고르고, 코드가 검사한 뒤 실행하고, 결과를 LLM에 돌려준다. 한 요청에 tool을 여러 개 부를 수 있다. 책은 LLM이 “카드 1번”, “장바구니 2번째”, “지금 보고 있는 책”으로만 가리키고, ISBN과 user_id는 코드가 채운다. 가격, 재고, 합계, 책 조합도 코드가 정한다.
3. 마무리. 위 “grounding 규칙”으로 답변의 숫자와 행동 서술을 검사하고, resolved_reference, selection, buttons를 조립한다.

코드가 강제하는 규칙:

• 직전 카드와 장바구니 목록에 없는 책은 실행하지 않는다.
• 어느 책인지 하나로 정해지지 않으면 실행하지 않고 되묻는다.
• 사용자의 말에 그 책을 가리키는 근거가 없으면 쓰기 tool을 실행하지 않는다. 근거는 그 책의 번호(“1번”, “두 번째”, “맨 위”), 같은 목록의 다른 책 제목에 없는 제목 낱말(맞춘 글자가 세 글자 이상), 전체 표현(“전부”), 목록에 책이 하나뿐인 경우다. 지금 보고 있는 책(focused_isbn)은 검사하지 않는다. 막히면 tool 결과에 REFERENCE_NOT_STATED가 남는다.
• logged_in이 false면 쓰기 tool을 막는다.
• 사용자가 책과 행동을 직접 말하면 바로 실행한다. 골라 담기처럼 AI가 고른 조합은 실행하지 않고 [담기] 버튼으로 확인받는다.
• 담기 전에 cart.add 안에서 BE의 장바구니를 다시 읽는다. 이미 담긴 책이면 담지 않고 ALREADY_IN_CART로 알려 준다.
• 골라 담기는 직전 카드 안에서만 고른다. 권수 조합을 전부 따져 book.offer의 가격 합계가 예산 이하이고 match_score 합이 최대인 조합을 selection.pick이 고른다.
• 비교에 쓴 소개글은 tool을 고르는 LLM에게 다시 보여 주지 않는다. 소개글 속 지시문이 tool 선택에 섞이지 않게 하기 위해서다.

tool 결과의 오류 코드

AI 서버가 BE를 부르기 전에 막거나 하지 않기로 한 것은 tool_calls[].result에 { "ok": false, "error": "코드" }로 남는다. 응답은 200이다. BE가 거절한 것(재고 부족, 30권 한도 등)은 BE의 오류 이름을 그대로 error에 적는다.

배포, 모니터링용 상태 점검. 요청 본문과 인증이 없으며, 응답 envelope의 유일한 예외다. 인증이 없는 대신 네트워크 레벨에서 내부망에만 노출한다. 커밋 해시, 구성 요소 상태가 밖으로 나가지 않도록.

입력

요청 본문, 쿼리 파라미터 없음.

출력 200

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

¹ 측정 불가면 null. status를 바꾸지 않는다 — 값이 낡아도 응답은 정상이다

• 복제 중단은 조회가 전부 정상이라 응답만 봐서는 감지되지 않는다. 감지 채널이 /health뿐이라 이 필드를 둔다. lag > N으로 지연을, null이 계속됨으로 중단을 잡는다.
• components 밖에 두고 status를 바꾸지 않는다. status는 배포 게이트와 로드밸런서가 읽는 값이라, 복제가 밀렸다고 degraded가 되면 멀쩡한 인스턴스가 트래픽에서 빠진다.

에러

인증 예외 엔드포인트라 401은 발생하지 않으며, 요청 본문이 없어 400도 해당 없다.

밤 배치가 ⑥을 다 부른 뒤 맨 끝에 부른다. ⑥을 부를 사용자가 없는 밤에도 부른다.

⑥은 추천 목록을 뽑을 때 관심사마다 조회 시간을 제한하고, 제한을 넘긴 관심사의 자리는 그 분류의 인기 책으로 임시로 채운다. 바뀐 것이 없는 사용자에게는 ⑥이 다시 불리지 않아 그 자리가 계속 남으므로, 이 호출이 그런 목록의 임시 자리를 다시 뽑는다. 저장해 둔 프로필로 계산해서 요청 본문은 없다.

응답의 remaining이 0이 될 때까지 다시 부른다. 서버가 한 번에 20초 안쪽에서 끊어 응답하므로 30초 클라이언트로 부른다. 한 밤에 한 목록은 한 번만 다시 뽑아서, 다시 넘기는 목록이 있어도 끝없이 돌지 않는다.

이 경로는 LLM과 임베딩을 호출하지 않으므로 503, 504가 없다.

입력

요청 본문 없음({}도 받는다).

출력 200

{
  "message": "refresh_success",
  "data": {
    "refreshed": 12,
    "remaining": 30
  }
}

다시 뽑을 목록이 없으면 refreshed와 remaining이 모두 0이다.

에러