Saram - Meridian

진료 기록 입력

왼쪽에 진료 기록을 입력하고
"변환하기"를 눌러주세요

초진 변환 후 추가 경과 기록을 입력하면
Patch Ops와 Diff가 여기에 표시됩니다

MCP 호출 이력이
여기에 표시됩니다

Saram 운영 흐름

자연어 임상 기록을 Agent Loop가 MCP 도구 호출로 구조화하고 원본 데이터까지 일관되게 관리합니다.

Schema Version 0.3.0

LLM Provider DeepSeek

Model deepseek-chat

Patch Engine v0.3 (4 ops)

원본 데이터 버전 saram-v1.0

사용법

페이지 로드 시 MCP로 세션이 자동 생성됩니다 (saram_session)
예제를 선택하거나 자연어 초진 기록을 입력합니다
"변환하기"를 누르면 Agent Loop가 saram_patch 등 MCP 도구를 호출해 State를 갱신합니다
아래 "추가 경과 기록"에 재진 기록을 입력합니다
"Patch 변환"도 Agent Loop 기반으로 처리되며, 호출된 tool 목록과 Diff가 표시됩니다
State 탭의 기본/원본/이력/리플레이 버튼으로 state, 내부 표준 원본(canonical_source), 변경 이력(canonical_history), 재생 검증 리포트(canonical_replay_report)를 조회할 수 있습니다
MCP Log 탭에서 모든 MCP 호출 이력을 확인합니다

MCP Tools (POST /api/mcp/saram)

Playground는 MCP(JSON-RPC) + Agent API를 함께 사용하는 내장 운영 클라이언트입니다.

saram_session	세션 관리 (create, list, get, delete)
saram_read	데이터 읽기 (state, patient, cc, encounters, history, context, stats, canonical_source, canonical_history, canonical_replay_report, fhir_bundle)
saram_patch	Canonical Patch 적용/검증 (apply, validate, format=canonical)
saram_export	내보내기 (json, csv, table)
resources_list	사용 가능한 리소스 목록 조회
resources_read	리소스 상세 조회 (saram://canonical_schema, saram://canonical_patch_schema, saram://operation_guide)

JSON-RPC 2.0 프로토콜. 자연어 처리는 Agent API(/api/saram/sessions/:id/agent)에서 MCP 도구 호출로 수행됩니다.

MCP Prompts (prompts/list, prompts/get)

MCP 표준 Prompts 기능으로 등록된 시스템 프롬프트입니다. prompts/get에 arguments를 전달하면 동적으로 생성된 messages를 받을 수 있습니다.

agent-loop	Agent Loop용. resources_list부터 시작하여 도구 호출로 차트 구성 (인자 없음)
chart-processing	자동화 파이프라인용. 스키마/매핑 내장, create/update 모드 지원 (`sessionId` 필수, `sync_mode` 선택)
convert	범용 변환용. State Context 포함 (`sessionId` 필수)

Canonical Patch Ops Reference

set	단일 필드 값 설정 `{ "op": "set", "path": ["patient", "id"], "value": "김동현_580312" }`
add	컬렉션에 항목 추가 `{ "op": "add", "path": ["problems"], "value": { "title": "요통", "status": "active" } }`
merge	기존 항목 병합 업데이트 `{ "op": "merge", "path": ["encounters"], "id": "enc_0001", "value": { "status": "finished" } }`
remove	ID 기준 항목 삭제 `{ "op": "remove", "path": ["problems"], "id": "prob_0001" }`

원자성 보장: 하나라도 실패하면 전체 롤백 (all-or-nothing)

State JSON 구조

schema_version: "0.3.0"
patient
  ├─ patient_id, sex, birth_date
  ├─ history
  │    ├─ conditions[]  (id, codes[], memo, active)
  │    ├─ family_history
  │    └─ social_history
  └─ baseline
       └─ items[]  (id, field, memo)
chief_complaints[]
  ├─ id, title, codes[], memo
  ├─ onset, status
encounters[]
  ├─ id, datetime, provider_id
  ├─ targets[]  ← cc의 id 목록
  ├─ progress_note
  ├─ examination  { items[] }
  ├─ assessment
  │    └─ diagnoses[]  (id, codes[], memo, targets[])
  ├─ plan
  │    └─ treatments[]  (id, type, memo, details{})
  ├─ metrics  { nrs }
  └─ vital_signs[]
memos[]

targets 결정 규칙

encounter.targets와 diagnoses.targets는 진단 내용과 chief_complaints 매핑 규칙에 따라 결정됩니다.

encounter.targets: 이 방문에서 다룬 chief_complaint의 id 목록
diagnoses.targets: 이 진단이 대응하는 cc의 id 목록
초진/재진 구분은 별도 필드 없이, "해당 cc를 처음 target한 encounter"가 초진으로 판단됨
추가 기록 변환 시 기존 State의 cc id를 참조하여 매핑

AI Context Window (buildStateContext)

추가 경과 변환 시, AI에게 State 전체를 보내지 않고 요약본만 전달합니다.
방문 300회 기준: 74,331자 → 939자 (99% 압축)

patient	전체 — 환자 기본정보, 과거력, baseline
chief_complaints	전체 — targets 매핑에 필수
_encounter_summary	총 방문 수, 마지막/다음 ID (enc, diag, trt)
recent_encounters	최근 2개 encounter 전체 (맥락 참고용)
memos	전체 — 메모 참고

추가 맥락이 필요하면 saram_read(target: encounters)로 특정 방문 기록을 조회해 보완할 수 있습니다.

AI 시스템 프롬프트 규칙

codes는 항상 빈 배열 [] (코드 없이 memo만 사용)
원본 텍스트를 임의 해석/추가하지 않고 있는 그대로 옮김
빈 증상, 템플릿 안내 문구("YYMMDD로 작성" 등)는 제외
생년월일 6자리 → YYYY-MM-DD 추론 (50이상 → 19XX, 미만 → 20XX)
날짜 형식 다양성 → 모두 YYYY-MM-DD로 정규화
treatment.type: herbal_medicine, acupuncture, cupping, moxibustion, chuna, other
temperature: 0.1 (정확한 변환 우선)
response_format: json_object (JSON만 출력)

ID 체계

cond_XXXX bl_XXXX cc_XXXX enc_XXXX diag_XXXX trt_XXXX exam_XXXX

XXXX는 0001부터 시작하는 4자리 자동 생성 번호. 전체에서 유니크.

Saram Playground