Studio 연동

이어 실행 규칙

• 추출은 단수 source_job_id 만 씁니다. 입력 File 목록은 source Job 의 파일 집합과 정확히 같아야 합니다(빠짐·추가·중복은 400).
• Import 판정과 이어 실행은 원본 Job 의 파일을 100개까지만 읽습니다. 넘으면 incomplete_job_lineage·import_input_invalid 로 이어받지 못하는데 분류 Job 생성은 막지 않습니다. 그래서 사건 서류를 여러 쪽 PDF 로 묶어 파일 수를 줄입니다(결정 20261021-case-documents-job-100-files 🟢).
• 그룹 요약은 source_job_id 대신 review_selector 로 분류 Job 의 일부 문서만 보냅니다. 둘을 함께 보내면 400 review_selector_conflict 입니다.
• LLM 탭1 의 input_job 은 이어 실행이 아니라 Job 결과 첨부입니다(include_parse:false). 탭2·3 은 Job 을 첨부하지 않습니다.
• 복수 source_job_ids 는 쓰지 않습니다.

Collection 을 찾는 방법 (보정 반영·그룹 요약 문서 읽기에 필요)

1. 설정 …_COLLECTION_ID 가 있으면 그 값.
2. 없으면 GET /agents/{a}/configs/{c} 의 Export 스텝 table_key 를 읽고
3. GET /search-collections?agent_id= 에서 같은 table_key 이고 종류가 agent_export(임대 서버는 source.type)인 항목을 고릅니다. 결과는 프로세스 안에 캐시합니다.

StudioCollectionResolver — 그룹 요약은 AI_PLATFORM_STUDIO_SUMMARY_GROUP_CLASSIFICATION_COLLECTION_ID 가 있으면 그 값, 없으면 분류 지시서로 찾고, 모르면 AI_SUMMARY_COLLECTION_UNKNOWN 으로 실패합니다.

보내는 것

POST /responses
{
  "model": "<분류 에이전트 id>",
  "config_id": "<분류 지시서 id>",
  "input": [{ "role": "user", "content": [
    { "type": "input_file", "file_id": "file_…" }, …   ← 묶음 PDF, 순서대로 이어 붙인 쪽 = 전체 쪽 번호
  ]}],
  "background": true, "stream": false,
  "metadata": { "report_no": "…", "step_code": "CLASSIFY" }
}

업로드: POST /files multipart(purpose=user_data), 파일 이름 {접수번호}-part-001.pdf. 파일명은 기본 한글 그대로(AI_PLATFORM_STUDIO_UPLOAD_FILENAME=utf8), 한글을 못 받는 Studio 로 되돌릴 때만 ascii. Content-Length 로 보냅니다(chunked 면 임대 서버 게이트웨이가 415).

읽는 것

• output[] 중 step_type = document-classify 의 content[] 하나 = 문서 하나.
• text = 라벨. additional_values 는 JSON 문자열이라 한 번 더 파싱합니다.
• 신뢰도: confidence → document_type.confidence_score → confidence_score 순으로 찾고, 0~1 밖이면 버립니다.
• 낱장 대응: 쪽 번호는 입력 파일을 순서대로 이어 붙인 전체 쪽입니다. page_ranges(1부터, 끝 포함)를 색인 InputPages(입력 파일 순서 × 파일 안 쪽 → 낱장)로 낱장에 옮깁니다. 결과가 파일 id 만 가리키면 그 파일이 한 쪽일 때만 파일로 되짚습니다 — 묶음 PDF 는 파일 하나에 문서가 여럿이라 쪽 범위로 가릅니다.
• 업스테이지 제공 분류 에이전트는 연속된 쪽을 문서 하나로 묶기도 합니다(문서 = 파일 + 쪽 범위). 그래서 문서 하나가 낱장 여러 장을 덮을 수 있습니다.
• 판정: 라벨이 미분류 목록(기타·미분류 등)이면 UNCLASSIFIED, 신뢰도가 없거나 0.700 미만이면 REVIEW_REQUIRED, 나머지 CLASSIFIED.

언제 도는가

• 분류: 추출을 보내기 직전, 이전 값과 다른 문서종으로 수동 지정한 보정이 있을 때만. AI 값을 그대로 확정한 것은 보낼 것이 없습니다.
• 추출: AI 보고서 탭1(v1 은 요약)을 보내기 직전, 분석 출처가 EXTRACT(기본, ANALYSIS_SOURCE_STEP)일 때. 저장된(STORED) 항목 중 output_pointer 가 있는 값만 보내고, 마스킹·미저장 항목은 SKIPPED.
• 쪽 단위: 보정이 여러 쪽 파일의 낱장을 가리키면 파일 안 쪽 번호(pageInFile)를 함께 보냅니다. 검수 JSON 경로는 문서의 source_files[].page_ranges 를 쪽으로 펴서 그 쪽만 새 문서로 떼고 이어진 쪽은 다시 접습니다. 제자리 교체 경로(임대 서버)는 파일 단위 자리만 알아 쪽 단위 보정을 건너뜁니다(경고 로그).
• 같은 결과에 이미 RESOLVED 된 반영이 있고 보정이 더 없으면 다시 돌지 않습니다.

실패하면 — AI_PIPELINE_CORRECTION_SYNC

• REQUIRED(기본): 반영 실패 = 단계 실패. 사람이 고친 값이 빠진 채 진행하지 않습니다.
• BEST_EFFORT: 원 Job 으로 그냥 진행.
• OFF: 반영하지 않음.
• 제한 시간 AI_PIPELINE_CORRECTION_SYNC_TIMEOUT 기본 30분.

보내는 것 — StudioReportLlmAdapter

POST /responses
{
  "model": "auto",                       ← 탭별로 바꿀 수 있음
  "input": [{ "role": "user", "content": [
    { "type": "input_job", "job_id": "<추출 Job>",
      "include_parse": false },          ← 탭1 만
    { "type": "input_text", "text": "<탭 프롬프트>" }
  ]}],
  "text": { "format": { "type": "json_schema", "name": "…",
            "strict": true, "schema": { … } } },
  "stream": true, "background": false
}

응답은 SSE 로 끝까지 읽습니다. Response id 를 받는 즉시 원장에 남기고, 응답을 잃으면 다시 보내지 않고 GET /responses/{id}(X-Use-Studio-Chat: true)로 다시 받습니다.

탭별 입력

• 탭1: 추출 Job 을 input_job 으로 첨부 + 탭1 프롬프트. 첨부할 Job 은 단계가 고정합니다 — 출처 EXTRACT(기본)면 결과 왕복으로 고친 값을 Studio 추출 결과에 되돌린 뒤 그 Job, CLASSIFY 면 왕복 없이 고정합니다.
• 수정값 줄: 두 구성 모두 탭1 지시문 끝에 「원문 값 → 수정값」 줄과 「수정값을 사실로 보고 그 값만 쓴다」 지시를 붙입니다(AnalysisSourceContext.correctionsBlock). 같은 문서종·낱장·항목은 마지막 값 하나로 합치고, 원문과 같으면 뺍니다. 10/22 E2E 에서 왕복만으로는 모델이 다른 문서 값을 써서 넣었습니다.
• 탭2·탭3: Job 첨부 없이 앞 탭 JSON 을 {{이전결과}} 로 받습니다.
• 템플릿: 관리자 에이전트 스튜디오 3단계 INSTRUCT 설정(DB)의 건에 고정한 판(인입 시점, 결정 20261028)에서 그 위탁사의 사용 중인 탭을 표시 순서대로 읽습니다(StudioInstructTemplateSource, 결정 20261023-report-llm-studio-instruct-source). 지시문 = 탭 프롬프트 → 고른 보고서 유형의 탭 본문(조건별 작성지침) → 공통 작성 규칙, 출력 JSON 골격은 text.format 스키마로 보냅니다. 화면에서 고치면 그 뒤 인입된 건부터 쓰입니다. 골격 칸이 JSON Schema 면 변환 없이 그대로 보냅니다(결정 20261029).
• 결과: 탭 출력 JSON 을 요약 결과(탭 원형)로 앉힙니다. 구역 키는 화면의 탭 키 tab-{위탁사 코드}-{탭 키}(스마트심사 매핑 기준), 구역 이름·반영 방식은 스튜디오 탭에서 옵니다. 키 순서는 출력 JSON 골격 순서로 맞추고, 탭1 의 근거 필드(근거)는 본문 카드 뒤로 갑니다. 신한 10/29 판은 최상위 근거 대신 사실 항목마다 요약근거[{job_id, occurrence_id}] 를 달고 낱장 출처로 잇습니다(결정 20261029-shinhan-summary-evidence-occurrence).

걸음 — AiSummaryGroupJobService · StudioGroupSummaryAdapter

1. 추출 Job 을 제출할 때(ExtractionSubmittedEvent) 그 분류 Job 으로 묶음(summary_group_batches) 1개를 만듭니다. v2 이고 포트가 있을 때만입니다.
2. GET …/review-capabilities 로 selective_import_supported 를 확인하고(1시간 캐시, 거짓이면 그룹 실패), GET …/review-document?job_ids=<분류 Job> 로 문서 id·라벨·구조 버전을 읽습니다.
3. 건에 고정한 판(summary_group_versions, 결정 20261028)의 그룹 마스터(summary_groups·summary_group_document_types, 한 문서종은 한 그룹에만)로 문서를 그룹에 나눠 그룹마다 1회 제출합니다.
4. 폴러가 결과를 받아 summary_group_runs 에 글과 인용(쪽·좌표)을 남깁니다.

POST /responses   (Idempotency-Key)
{ "model": "<요약 에이전트>", "config_id": "…",
  "review_selector": [{ "job_id": "<분류 Job>",
     "structure_version": N, "document_ids": ["rdoc_…"] }],
  "input": [{ "role": "user", "content": [
     { "type": "input_text", "text": "<그룹 프롬프트>" } ]}],
  "background": true, "stream": false }

다시 만들기 · 재사용

• 분류 Job 이 바뀌면(다시 분석·추가 서류) 새 묶음을 만들고 앞 진행 중 묶음은 SUPERSEDED 로 닫습니다.
• 같은 분류 Job 으로 진행 중·완료된 묶음이 있으면 만들지 않습니다(추출부터 다시 분석해도).
• 실패한 묶음은 다음 추출 제출 때 다시 만들고, 같은 입력(fingerprint)으로 성공했던 그룹은 다시 부르지 않습니다(REUSED).
• source_job_id·input_file 은 싣지 않습니다.
• 에이전트·지시서를 따로 주지 않으면 요약(analysis) 설정의 것을 씁니다.

화면 · API

• GET /api/v1/investigation-reports/{reportNo}/summary-groups/latest — 진행 중이면 화면이 10초마다 다시 받습니다.
• 관리자 그룹 편집 GET·PUT /api/v1/admin/agent-studio/summary-groups

지시문 전달 — AI_PLATFORM_STUDIO_ANALYSIS_INSTRUCTION_DELIVERY

• auto(기본): input_text 로 먼저 보내고, 400 import_input_invalid(임대 서버)이면 실행별 지시서 방식으로 넘어갑니다. 출력 골격이 있으면 처음부터 지시서 방식.
• input-text: input_text 만. 거절되면 실패.
• config-version: 기준 지시서를 GET /agents/{a}/configs/{c} 로 읽어 Instruct 의 queries·response_format(json_schema hwss_summary_sections)을 바꾼 비기본 지시서를 POST /agents/{a}/configs(이름 hwss-run …)로 만든 뒤 그 지시서로 제출.

결과 읽기 — StudioAnalysisOutputParser

• 진행 중에는 ?include=last 로 가볍게 보고, completed 일 때만 ?include=all 로 받아 step_type = instruct 출력을 읽습니다(분류·추출도 같은 방식, StudioJobPoll).
• SaaS 의 Import → Merge → Instruct 는 같은 글이 문서 수만큼 반복되어 와서 한 번만 읽습니다.
• Merge 없는 구성(임대 서버)은 문서마다 Instruct 가 돌아 카드를 순서대로 이어 붙입니다.
• text 는 두 겹까지 감싼 JSON 을 벗기고, 인용 표식 【†n】 을 걷어냅니다.
• 형태: 우리 골격 sections[] / 지시서가 정한 탭 객체 / 카드 배열 / 그 밖의 글(요약 카드 1장).

① 의도 게이트

• POST /responses, stream:false, conversation 없음, reasoning.effort:"none"·temperature:0, function 툴 1개(기본 이름 intention-classify, 인자 mode 만)를 tool_choice 로 강제합니다. 모델 기본 solar-pro4.
• 답: mode 하나(GENERAL·FOLLOWUP·DOCUMENT). 세 값이 아니거나 실패하면 DOCUMENT 입니다.

② 컬렉션 라우팅

• POST /vector_stores/route. GENERAL 이면 부르지 않습니다. 요청은 query, 공용 Store 전부(vector_store_ids), missing_description:"exclude", include_reasons:true, 있으면 conversation. model 은 서버 설정이 정합니다.
• 실패하면 고른 것 없이 이어 갑니다. 지정·개인 Store 는 라우팅과 무관하게 ③ 에 합칩니다.

③ 본 답변

• stream:true, background:false, instructions = 답변 규칙 + 고정 전제 + 범위 밖 정책.
• 검색이 필요한 턴에만 file_search(vector_store_ids, max_num_results 30)를, 첨부가 있는 턴에만 doc_chat:auto 를 선언합니다. 출처는 include:["file_search_call.results"] 로 받습니다.
• 후속 질문은 이번 질문만 싣고 conversation:{id}(객체 — 문자열이면 400)로 잇습니다. SSE 의 마지막 response.conversation.id 를 chat_sessions.external_conversation_id 에 둡니다(결정 20261020-chat-studio-conversation-continuation).

사고조사 챗봇

• API /api/v1/investigation-reports/{reportNo}/chat(InvestigationChatController) — 질문·첨부·지식 선택·삭제, 답변의 AI 보고서 반영(…/messages/{id}/reflect). 저장 구조는 결정 20261023-investigation-chat-session-structure.
• InvestigationTurnPrompt 가 턴 지시문을 조립하고, 어댑터가 같은 보고서의 분류·추출 Job 을 input_job 으로 첨부합니다. 사건 서류 Store 는 분류 에이전트의 Store 입니다(StudioCaseDocumentStoreAdapter, GET /agents/{a}).
• 범용 챗봇과 같은 세 호출입니다. 통합 설계 v0.4 는 「의도 분류는 없다」, 업스테이지 회신은 「동일하게 3단계」라 확인 중입니다(docs/external/README.md).

업스테이지 확인 · 운영 환경

• 운영 1.6.12 실호출 — selective_import_supported 등 기능이 켜져 있는지, 호출 동작(판은 10/30 측정, 동작은 미확인)
• 임대 서버 원본 교체 퇴역 시점(퇴역하면 임대 서버 보정 반영 불가)
• 운영 API 키 종류와 x-project-id 필요 여부, 오프라인 토큰 유출 시 무효화 절차
• 실서류 SaaS 전송 — 개발 서버는 허용(결정 20261014 개정), 위탁사 승인 범위·운영 환경은 확인 필요
• 통합 설계 v0.3 문서 안 불일치 7건 회신(docs/external/README.md 「통합 설계 v0.3 수령 검토」)
• v2 경로(review_selector·LLM input_job)의 운영(1.6.12) 실호출 확인. 임대 서버는 대상 아님
• 통합 설계 v0.4 — 사고조사 챗봇에 ① 의도 게이트를 두는가(docs/external/README.md 「통합 설계 v0.4 수령 검토」)

우리 설계

• 탭 JSON 을 화면 블록으로 그리는 규칙(결정 20261007 개정 대기) — 지금은 탭 원형 투영 그대로
• 「요약」 탭 출력 형식, 그룹 안 나눔 기준(결정 20261019 「추가」 3항 🔴), 초안 단계 「요약」 탭 텍스트박스
• 청구병원 선택 자리({{선택된병원}})
• v1 사건 데이터를 v2 로 옮길지(정하지 않음), v1 실행별 지시서 hwss-run … 누적 정리
• 지식컬렉션의 접속 대상 구분, 같은 File 의 두 Store 사용
• 새 어댑터(LLM 탭·그룹 요약·채팅 세 호출)의 계약 테스트 녹화, 그룹 요약에 경합 재시도 한도 적용 여부