📖 매뉴얼 (한국어)

CNA v7 사용자 매뉴얼 (한국어)

Catcher Navigator Algorithm v7.0
Boston Neuromind LLC · 2026

목차

  1. 시스템 소개
  2. 핵심 개념
  3. 설치 가이드
  4. 첫 클라이언트 시작 워크플로
  5. Entry Protocol 5 측정 가이드
  6. 시간 정보 수집 가이드 (v7 NEW)
  7. 임상 리포트 해석
  8. 감별 진단 + 공존 진단 해석 (v7 NEW)
  9. 훈련 프로토콜 운영
  10. 위기 대응
  11. 4주 후 Outcome + Adaptive Re-routing (v7 NEW)
  12. 고급 - 매핑 행렬 조정
  13. API 사용 가이드
  14. 문제 해결

1. 시스템 소개

1.1 무엇을 하는 시스템인가

CNA v7은 5명 베타 클라이언트 (파트타임 세라피 고객)를 위한 임상 의사결정 지원 시스템입니다.

v7 핵심 추가 (Round 7-10): - Differential Diagnosis Engine (DDE): 클라이언트 데이터 → Bayesian 감별 진단 (ADHD/GAD/MDD) - Comorbidity Decomposition: 한 임상 점수를 진단 source별로 분해 - Cognitive Simulator: 인지축 변경 시 임상 결과 시뮬레이션 (counterfactual) - Adaptive Re-routing: 4주 outcome으로 진단 자동 재구성

핵심 기능:

1.2 사용 대상

1.3 임상 근거

매핑 / 알고리즘 임상 근거
Working Memory → Learning (r=0.43) Meta-analysis, n=7947
Emotional Intelligence → Academic (r=0.39) EI-AP meta-analysis
Emotion Regulation 효과 (d=0.605) Aldao et al. 2010
Rumination → Depression (양방향) Nolen-Hoeksema response styles
Active Inference 임상 적용 Friston 2010-2025
ADHD 공존률 50-80% (성인) Frontiers 2025
ADHD-불안 25-50%, ADHD-우울 ~50% Postgraduate Med 2014
감별의 핵심 = temporal pattern ADHD 만성/광범위 vs 불안/우울 에피소드
미인지 ADHD에 SSRI 단독 = 실패 McIntosh et al. 2009

2. 핵심 개념

2.1 Fischer 인지 5축 (Layer A)

측정 가능한 인지 능력 자료:

축 측정 도구 정상 범위
지속 주의력 (Sustained Attention) CPT (Continuous Performance Test) Omissions Z = -0.5 ~ +0.5
작업기억 (Working Memory) N-back (2-back, 3-back) 정확도 70-85%
정서조절 (Emotional Regulation) HRV RMSSD + VSR RMSSD 25-50ms
시간감각 (Time Awareness) 시간추정 과제 오차 5-15%
자기인지 (Self-Awareness) OMR (Observable Model Refinement) 응답 깊이 자료

Fischer Level: L7.0 ~ L13.0 (성인 일반 범위)

2.2 임상 결과 5축 (Layer B)

클라이언트가 선택 가능한 치료 영역 자료:

영역 한국어 주요 측정 자료
Attention 주의력 CPT, ASRS
Learning 학습 효율 N-back, 학습 retention
Peak Performance 수행 최적화 시간 추정, HRV
Anxiety 불안 관리 HRV, GAD-7
Depression 기분 안정 PHQ-9, BA count

2.3 4-Vector 입력 자료

시스템이 의사결정에 사용하는 4가지 자료:

2.4 Free Energy 6-Component 의사결정

각 카드는 6개 자료로 점수 계산:

  1. Accuracy (Symptom): 클라이언트 증상 ↔ 카드 타겟 매칭
  2. Accuracy (Biomarker): 측정값 ↔ 카드 expected profile
  3. Complexity Penalty: Fischer level 거리 (Vygotsky ZPD)
  4. Preference: 클라이언트 선택 영역 정합
  5. Epistemic Value: 자료 탐색 가치 (information gain)
  6. Pragmatic Value: 근거 + 즉시 효과

가중치는 클라이언트 phase에 따라 자동 조정: - 새 클라이언트: epistemic 우선 (자료 잡기) - 안정 클라이언트: pragmatic 우선 (효과) - 위급 클라이언트 (priority tier): emergency phase 자동 활성, pragmatic 최우선

3. 설치 가이드

3.1 시스템 요구사항

3.2 설치 단계

# 1. ZIP 풀기
unzip cna_v6_complete.zip
cd cna_v6

# 2. 가상환경 생성 (한 번만)
python -m venv venv

# 3. 활성화
source venv/bin/activate     # Mac/Linux
# 또는
venv\Scripts\activate         # Windows

# 4. 패키지 설치
pip install pydantic numpy pyyaml fastapi uvicorn

# 5. 통합 테스트 (시스템 작동 확인)
python tests/test_integration.py

테스트 통과 시: "✓ 전체 통합 테스트 통과" 메시지 확인.

3.3 디렉토리 구조

cna_v6/
├── config/                          # 할비 수정 가능
│   ├── cognitive_clinical_mapping.yaml
│   └── free_energy_weights.yaml
├── cna_core/                        # 핵심 로직 (수정 금지)
│   ├── types.py
│   ├── cognitive_clinical_mapper.py
│   ├── free_energy_scorer.py
│   ├── biomarker_normalization.py
│   ├── clinical_report.py
│   ├── card_deck.py
│   ├── crisis_detection.py
│   ├── protocol_generator.py
│   ├── variational_update.py
│   └── orchestrator.py
├── tests/test_integration.py
├── cli/run_assessment.py
├── api/main.py                      # FastAPI 서버
├── supabase/schema.sql
└── README.md

4. 첫 클라이언트 시작 워크플로

4.1 회기 1 (초기 평가) — 75-105분 (v7은 시간 정보 인터뷰로 약 15분 추가)

Step 1: 클라이언트 등록 (5분)

Step 2: Entry Protocol 5 측정 (30분)

종이 측정 시트 사용. 5가지 측정:

  1. 시간 추정 (5분) → time_awareness
  2. HRV (5분, Polar H10 또는 Apple Watch) → emotional_regulation
  3. CPT (15분, 종이 또는 디지털) → sustained_attention
  4. N-back (10분, 2-back 3-back) → working_memory
  5. VSR (선택, 5분) → 추가 측정

Step 3: 증상 자료 수집 (15분)

Step 4 (v7 NEW): 시간 정보 인터뷰 (15분) ⭐

DDE 정확도의 핵심. 자세한 가이드는 6장 참조. 핵심 8문항:

  1. "증상이 처음 나타난 나이는?" → onset_age
  2. "아동기/청소년기/성인기?" → onset_category
  3. "만성적으로 지속? 에피소드처럼 왔다 갔다?" → course
  4. "현재 증상이 몇 개월째?" → duration_months
  5. "여러 환경에서 일관되게? 특정 상황에만?" → pervasiveness
  6. "스트레스로 악화되나? 휴식 시 호전?" → stress_triggered
  7. "가족력?" → family_history
  8. "이전 치료 반응?" → prior_treatment_response

Step 5: 클라이언트 목표 청취 (10분)

4.2 CLI 실행 (5분)

cd cna_v7
source venv/bin/activate
python cli/run_assessment.py

대화형 질문이 나오면 수집한 자료 입력. 또는 JSON 파일 사용:

python cli/run_assessment.py --json patient_001.json

patient_001.json 예시:

{
  "patient_id": "AK001",
  "cognitive_levels": {
    "sustained_attention": 8.5,
    "working_memory": 9.0,
    "emotional_regulation": 8.5,
    "time_awareness": 9.0,
    "self_awareness": 9.5
  },
  "biomarkers": {
    "cpt_omissions_zscore": -0.5,
    "hrv_rmssd": 30.0,
    "nback_accuracy": 0.75,
    "time_estimation_error_pct": 15.0
  },
  "symptoms": {
    "inattention": 0.4,
    "distractibility": 0.35,
    "executive_dysfunction": 0.3,
    "anxiety_somatic": 0.3,
    "anxiety_cognitive": 0.3,
    "low_mood": 0.2,
    "low_motivation": 0.2
  },
  "temporal_history": {
    "onset_age": 8,
    "onset_category": "childhood",
    "course": "chronic",
    "duration_months": 240,
    "pervasiveness": "cross_setting",
    "stress_triggered": false,
    "family_history": ["father_ADHD"],
    "prior_treatment_response": {}
  },
  "primary_axis": "learning",
  "motivation": 0.7,
  "n_sessions": 0
}

temporal_history 필드 (v7 NEW) — DDE 정확도에 결정적. 6장 참조.

4.3 결과 확인 (15분)

시스템이 출력: 1. 임상 5축 예측표 — 클라이언트와 함께 검토 2. 5축 관계표 — 부수 효과 3. 감별 진단 결과 (v7 NEW) — Primary/Secondary + Comorbidity pattern 4. 공존 진단 분해표 (v7 NEW) — 각 임상축의 source별 기여 5. 개입 우선순위 표 (v7 NEW) — 어느 인지축이 가장 효과적? 6. 목표 Level 추천 (v7 NEW) — 임상 목표 도달까지 필요한 Level 7. 시스템 추천 카드 3개 — 임상가 검토 8. 8주 프로토콜 미리보기 — 클라이언트 동의 + 효과 시뮬레이션 (v7 NEW)

결과는 outputs/{patient_id}_{timestamp}.json으로 자동 저장.

5. Entry Protocol 5 측정 가이드

5.1 시간 추정 (Time Estimation)

측정: - 클라이언트에게 "30초가 지났다고 생각되면 손을 들어주세요" 안내 - 5회 반복 - 각 회기 오차 % 계산 - 평균 오차 % → time_awareness Level 변환

해석: | 평균 오차 | Fischer Level | 임상 자료 | |---------|---------------|----------| | 0-5% | L11+ | 매우 정확 | | 5-12% | L9-10 | 정상 | | 12-25% | L8 | 약함 | | 25%+ | L7 이하 | 임상 주의 |

5.2 HRV 측정 (RMSSD)

측정: - Polar H10 또는 Apple Watch 사용 - 5분 안정 호흡 (앉은 자세) - RMSSD 자동 계산 - LF/HF 비율 자료 함께 기록

해석: | RMSSD (ms) | 자료 | |----------|------| | 50+ | 매우 좋음 | | 35-50 | 좋음 | | 25-35 | 보통 | | 15-25 | 약함 | | < 15 | 임상 주의 |

5.3 CPT (Continuous Performance Test)

측정 자료: - Conners CPT, IVA-2, 또는 자체 도구 사용 - 15분 표준 프로토콜 - 결과: omissions, commissions, RT variability

Z-score 변환: - Norm 평균 = 0, SD = 1 - 클라이언트 점수 → Z-score (positive = 더 좋음) - omissions Z < -1.5 = 임상 자료

5.4 N-back

측정 자료: - 2-back 5분, 3-back 5분 - 정확도 % 기록 - d-prime 계산 (signal detection)

해석: | 2-back 정확도 | Fischer Level | |--------------|---------------| | 90%+ | L11+ | | 75-90% | L9-10 | | 60-75% | L8 | | < 60% | L7 |

5.5 VSR (선택)

측정: - 800셀 stem reading - Acoustic 분석 → 4차원 매핑 - consistency score 0-1

6. 시간 정보 수집 가이드 (v7 NEW)

6.1 왜 결정적인가

DDE (Differential Diagnosis Engine)의 4-source likelihood 중 temporal 가중치 30%. 시간 정보가 빠지면 감별 정확도가 크게 떨어집니다.

임상 근거: ADHD vs GAD vs MDD 감별의 핵심은 시간 패턴입니다. - ADHD: 아동기 발병 (< 12세), 만성, 여러 환경에서 일관 - GAD: 성인 발병 가능, 6개월+, 스트레스 유발 - MDD: 2주+ 에피소드, 전반적 환경 영향

6.2 8문항 인터뷰

1. 발병 나이 (onset_age)

2. 발병 단계 (onset_category)

3. 경과 (course)

4. 지속 기간 (duration_months)

5. 광범위성 (pervasiveness)

6. 스트레스 유발 (stress_triggered)

7. 가족력 (family_history)

8. 이전 치료 반응 (prior_treatment_response)

6.3 데이터 입력 예시

from cna_core import TemporalHistory

temporal = TemporalHistory(
    onset_age=8,
    onset_category="childhood",
    course="chronic",
    duration_months=240,
    pervasiveness="cross_setting",
    stress_triggered=False,
    family_history=["father_ADHD"],
    prior_treatment_response={"SSRI": "no_response"},
)

6.4 인터뷰 팁

7. 임상 리포트 해석

7.1 5축 예측표 읽기

【 임상 5축 예측 자료 】
  영역             점수    단계               우선  주요 기여 인지축
  주의력            0.39   주의 ⚠              #1    지속 주의력 (+0.05)
  불안 관리          0.14   임상 우선 ⚠⚠         #2    정서 조절 (-0.27)
  ...

점수 해석: - 0.75+ : 매우 우수 (개입 불필요) - 0.60-0.75: 우수 (유지) - 0.45-0.60: 보통 (관찰) - 0.30-0.45: 주의 (개입 고려) - < 0.30: 임상 우선 (즉시 개입)

우선순위: - #1: 클라이언트 선택 영역 (autonomy 우선) - #2: priority tier (< 0.30) - #3: 높은 leverage 영역 - #4: 약화 영역 - #5: 안정 영역

7.2 5축 관계표 해석

【 5축 간 관계 자료 (Leverage 순) 】
  A 축          관계         B 축          강도   Leverage
  불안 관리       ↑↑ 동반 변화    기분 안정       0.65   0.62
  ...

관계 유형: - 동반 변화 (↑↑): 한 축 좋아지면 다른 축도 좋아짐 - 반대 변화 (↑↓): 한 축 좋아지면 다른 축은 나빠짐 (드물지만 가능)

Leverage 점수: - 0.5+: 매우 큰 부수 효과 (이 축 개입 시 다른 축도 같이 변화) - 0.3-0.5: 중간 부수 효과 - < 0.3: 약한 부수 효과

임상 적용: - Leverage 0.5+ 영역에 개입 = 효율적 - 클라이언트가 영역 선택 시 leverage 자료 보여주고 안내

8. 감별 진단 + 공존 진단 해석 (v7 NEW)

8.1 DDE 결과 읽기

【 Differential Diagnosis 자료 】
  Primary: adhd_inattentive
  Secondary: ['mdd', 'gad']
  Comorbidity pattern: adhd_plus_gad
  Confidence: 0.64
  Treatment 자료: ADHD + 범불안장애 표준. 공존률 30% 임상 패턴.

  진단 가설 순위:
    ★ Primary: ADHD 주의력 결핍 우세형 (P=57%)
           Symptom match: 0.99, Cognitive: 0.99, Biomarker: 0.98, Temporal: 0.95
           ✓ 충족: Cross-setting consistency, Onset before age 12
    • Secondary: 주요 우울장애 (P=21%)
    • Secondary: 범불안장애 (P=21%)

Primary 임계값: - Posterior > 40%: 강한 신호, primary 확정 - Posterior 30-40%: primary로 두지만 검토 권고 - Posterior < 30%: primary 미정 (검토 자료)

Secondary: Posterior > 20%

Confidence: - 0.7+: 매우 신뢰 - 0.5-0.7: 적당히 신뢰 - < 0.5: 추가 평가 필요

8.2 4-Source Likelihood 자료

Source 가중치 자료
Symptom match 40% 클라이언트 호소 증상 vs 진단 패턴
Cognitive match 20% 인지 5축 약화 패턴
Biomarker match 10% CPT/HRV/N-back 등 객관 측정
Temporal match 30% 시간 정보 (감별의 핵심)

catch 자료: Symptom + Temporal = 70%. 이 두 정보가 가장 결정적.

8.3 Differential Markers 충족/미충족

각 진단의 DSM-5-TR 기준 자동 catch:

ADHD inattentive: - ✓ Cross-setting consistency (pervasiveness == "cross_setting") - ✓ Onset before age 12 (onset_age < 12) - ✓ Not better explained by mood/anxiety (증상 패턴 분석)

GAD: - ✓ Excessive worry 6+ months (duration >= 6) - ✓ Worry > attention deficit (불안 > 부주의 증상) - ✓ HRV RMSSD < 25ms

MDD: - ✓ Anhedonia or low mood 2+ weeks - ✓ Rumination (vs ADHD distractibility) - ✓ Cognitive slowing (vs ADHD inconsistency)

8.4 Comorbidity Decomposition 해석

【 공존 진단 분해 자료 】
  ▶ 주의력
     원 점수: 0.38 (약화 0.62)
     설명력: 83%
     ★ ADHD 주의력 결핍 우세형           기여 0.234 (posterior 57%)
     • 주요 우울장애                   기여 0.087 (posterior 21%)
     • 범불안장애                     기여 0.087 (posterior 21%)
     잔차 (미설명): 0.105
     치료 target: primary_first

기여도 해석: - ADHD 0.234 → 주의력 약화의 23.4%가 ADHD source - MDD 0.087 → 8.7%가 우울로 인한 2차 - 잔차 0.105 → 시스템이 설명 못 하는 자료 (개인 차이, 기타 요인)

치료 target: - primary_first: Primary 진단부터 치료 (이 임상축이 primary source) - concurrent: 동시 치료 (Comorbidity pattern) - monitor: 관찰

8.5 임상가 검토 자료 catch

시스템이 자동으로 검토 권고: - 진단 확실성 낮음 (top posterior < 40%) - 시간 정보 부족 (onset/course unknown) - 감별 어려움 (1순위 vs 2순위 격차 < 10%) - ADHD 의심인데 발병 나이 미확인

검토 권고 시 임상가가 직접 결정 (시스템 자동 결정 X).

8.6 개입 우선순위 (Counterfactual)

【 개입 우선순위 자료 】
  #1 working_memory      L8.2→L9.2 | 전체 +0.085 | 주 효과: learning
  #2 sustained_attention L7.8→L8.8 | 전체 +0.062 | 주 효과: attention
  ...

각 인지축 +1.0 Level 적용했을 때 효과 비교. 1순위가 가장 효율적.

9. 훈련 프로토콜 운영

9.1 영역별 프로토콜

영역 기간 회/주 진행 자료
주의력 4주 3회 Complexity ramp (난이도 점진 증가)
학습 효율 4주 4회 Consolidation (반복 후 확장)
수행 최적화 4주 3회 Skill stacking (스킬 누적)
불안 관리 4주 5회 Exposure gradient (점진 노출)
기분 안정 8주 4회 Behavioral activation

7.2 회기별 자료 운영

각 회기: 1. 시작 (5분): HRV 측정, 기분 자료 체크 2. 카드 실행 (15-60분): 시스템 추천 카드 자료 3. 종료 (5분): HRV 재측정, OMR 응답 자료

7.3 주간 측정 자료

7.4 임상가 Override 자료

시스템 추천이 임상적으로 부적합한 경우: - 임상가가 다른 카드 선택 가능 - override 사유 자료 기록 필수 (학습 신호) - 시스템이 이 자료를 ×2 weight로 학습

10. 위기 대응

8.1 자동 감지 자료

시스템이 클라이언트 발화에서 10개 위기 자료 자동 catch:

자료 Severity 즉시 조치
수동적 자살 생각 moderate 회기 계속 + 안전 점검
능동적 자살 생각 high 회기 중단 + Columbia SSRS
자살 계획/수단 imminent 119/911 + 클라이언트 혼자 두지 않음
최근 자해 high 회기 중단 + 안전 계획
타살 의도 imminent Tarasoff 의무 + 법 집행 통보
정신증 활성 high 정신과 의뢰
급성 중독 high 회기 연기 + 안전 귀가
가정폭력 진행 imminent DV Hotline + DCF (자녀 있을 시)
아동학대 공개 imminent MA DCF 800-792-5200 즉시 신고
심한 해리 moderate Grounding + PTSD/DID 평가

8.2 MA Mandated Reporter 자료

중요: 할비 (BCN + PhD) = MA M.G.L. c. 119 §51A "allied mental health professional" 카테고리.

의무 자료: 1. 즉시 구두 신고: MA DCF Emergency Line 1-800-792-5200 2. 48시간 내 서면 보고: 51A form (online portal) 3. 위반 시 벌금: 1회 $1,000, 이후 $5,000

대상 자료: - 아동 (18세 미만) 학대/방치 - 장애인 학대 (DPPC Hotline 1-800-426-9009)

8.3 PHQ-9 9번 통합 자료

PHQ-9 9번 ("죽음 또는 자해 생각") 점수 자동 catch: - 1점 이상: passive ideation 활성 - 2점 이상: active ideation 활성 - 3점 이상: plan/means 자료 가능성

CLI에서 PHQ-9 자료 입력 시 자동 감지.

11. 4주 후 Outcome + Adaptive Re-routing (v7 NEW)

11.1 4주 후 측정

회기 종료 후 4-8주 (영역별 다름):

  1. Entry Protocol 5 재측정 — 모든 측정 다시
  2. 임상 5축 점수 평가 — 임상가 평가
  3. 자기 보고:
  4. 개선 정도 (0-10)
  5. 만족도 (0-10)
  6. PHQ-9 / GAD-7 재측정

11.2 CLI Outcome 입력

python cli/run_assessment.py --outcome

자료 입력: - Episode ID (이전 회기에서 받은 자료) - Outcome score (-1.0 ~ +1.0, 0이 변화 없음) - 인지 5축 변화 (cognitive_after) - 임상 5축 변화 (clinical_after) - 측정 분산 (자료 신뢰도) - Primary intervention axis (어느 임상축에 개입했나) - Intervention card IDs (적용한 카드)

11.3 시스템 자동 학습

Outcome 기록 시:

기본 학습 (v6): 1. 가중치 자동 조정 (variational update) 2. 매핑 행렬 보정 (calibration history) 3. Prediction error 누적 (구조적 misfit 감지) 4. Crisis FN/FP 추적

Adaptive Re-routing (v7 NEW): 5. 예상 반응 vs 실제 반응 비교 6. 불일치 시 DDE 자동 재실행 (weakened prior) 7. 진단 변경 catch (no_change | secondary_added | primary_swap | diagnosis_dropped)

11.4 Re-routing 결정 해석

【 진단 자료 재구성 결정 】
  Primary: adhd_inattentive → gad
  Secondary: [] → [adhd_inattentive]
  변경 여부: 예
  변경 유형: primary_swap
  반응 패턴: primary_no_response_secondary_improved_anxiety
  Posterior 변화: 0.35
  ⚠ 임상가 검토 필요

변경 유형: - no_change: 진단 유지 (반응 fit 0.60+) - secondary_added: 새 공존 진단 catch - primary_swap: Primary 진단 변경 (예: ADHD → GAD) - diagnosis_dropped: 이전 진단 제외

반응 패턴: - expected_response_strong: Primary target 잘 반응 (>+0.15) - partial_response: 부분 반응 - primary_no_response_secondary_improved_*: Primary 무반응 + 다른 축만 반응 → 진단 의심 - treatment_no_response: 전혀 반응 X - diagnosis_revision_from_response: 반응이 다른 진단 패턴

11.5 임상 자료 — Re-routing 시나리오

시나리오 A: ADHD primary → 자극제 카드 → 효과 ❌, 불안만 ↑ - 시스템 catch: "ADHD primary일 줄 알았는데 자극제 무반응 + 불안 악화" - Re-routing: GAD primary로 변경, ADHD secondary로 - 임상적 의미: GAD가 ADHD-like 증상 일으킨 것 (Eysenck ACT)

시나리오 B: MDD primary → BA 카드 → 기분 변화 ❌, HRV만 ↑ - 시스템 catch: "MDD 치료에 우울 반응 ❌" - Re-routing: GAD secondary 가능성 ↑ - 임상적 의미: 우울증보다 만성 불안이 primary

시나리오 C: ADHD primary → 자극제 카드 → 주의력 ↑, 학습 ↑ - 시스템 catch: "예상대로 반응 (response fit 0.85+)" - Re-routing: 변경 없음, 진단 신뢰도 ↑

11.6 안전 자료

12. 고급 - 매핑 행렬 조정

12.1 언제 조정?

12.2 수정 위치

파일: config/cognitive_clinical_mapping.yaml

positive_loading:
  sustained_attention:
    attention:        0.45   # ← 이 숫자 수정 가능
    learning:         0.20
    peak_performance: 0.20
    anxiety:          0.05
    depression:       0.10

규칙: 1. 행 합 = 1.0 유지 (각 인지축의 영향력 분배) 2. 행/열 구조는 건드리지 않음 3. 코드 변경 없이 YAML만 수정 4. 수정 후 통합 테스트 다시 실행: bash python tests/test_integration.py

12.3 Protected Cells

학습으로도 변경되지 않는 셀:

imperturbable:
  protected_cells:
    - [emotional_regulation, anxiety]
    - [working_memory, learning]
    - [sustained_attention, attention]
    - [emotional_regulation, depression]

강한 임상 근거 자료가 있는 셀 자료입니다. 변경 시 신중.

13. API 사용 가이드

13.1 서버 시작

cd cna_v6
source venv/bin/activate
uvicorn api.main:app --reload --port 8000

브라우저에서 자료 확인: http://localhost:8000/docs

13.2 주요 Endpoints

Endpoint 메서드 설명
/health GET 시스템 상태
/cards GET 카드 자료 조회
/full-cycle POST 전체 사이클 한 번에
/assess POST Loop 1-2 평가
/protocol/generate POST 프로토콜 생성
/safety/check POST Crisis 자료 검사
/system/state GET 학습 상태 자료

13.3 예시 호출

# Full cycle 자료
curl -X POST "http://localhost:8000/full-cycle" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "AK001",
    "cognitive_levels": {
      "sustained_attention": 8.5,
      "working_memory": 9.0,
      "emotional_regulation": 8.5,
      "time_awareness": 9.0,
      "self_awareness": 9.5
    },
    "symptom_vector": {"inattention": 0.4},
    "biomarkers": {"hrv_rmssd": 30.0},
    "primary_clinical_axis": "learning",
    "motivation": 0.7,
    "n_sessions": 0
  }'

13.4 learning.neurocatchers.com 통합

CORS 자료 자동 활성: - https://learning.neurocatchers.com - https://neurocatchers.com - https://bostonneuromind.com

JavaScript 호출 예:

const response = await fetch('https://cna-api.example.com/full-cycle', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify(patientData)
});
const result = await response.json();

14. 문제 해결

14.1 Python 오류

증상: ModuleNotFoundError: No module named 'pydantic'

pip install --upgrade pydantic numpy pyyaml fastapi uvicorn --break-system-packages

14.2 통합 테스트 실패

증상: test_integration.py 에러

# 1. 가상환경 활성화 확인
source venv/bin/activate

# 2. 패키지 재설치
pip install -r requirements.txt

# 3. config 파일 자료 확인
python -c "import yaml; yaml.safe_load(open('config/cognitive_clinical_mapping.yaml'))"

14.3 행 합 자료 검증

매핑 행렬 수정 후:

python -c "
import yaml
cfg = yaml.safe_load(open('config/cognitive_clinical_mapping.yaml'))
for axis, row in cfg['positive_loading'].items():
    total = sum(row.values())
    print(f'{axis}: {total:.4f}')
"

각 행 = 1.0 ± 0.001 자료.

14.4 카드 자료 추가

cna_core/card_deck.py 자료에 새 Card 객체 추가:

Card(
    id="att-007",
    target_symptoms={"inattention": 0.6},
    target_fischer_levels={"sustained_attention": 9.0},
    target_clinical_axes=["attention"],
    evidence_d=0.5,
    text_ko="새 카드 자료 설명",
    text_en="New card description",
    cost_minutes=15,
    expected_outcome=0.55,
),

14.5 Supabase 연결 자료

베타 시작 전 자료: 1. Supabase Project 생성 (Pro $25/월) 2. supabase/schema.sql 실행 3. RLS 정책 확인 4. HIPAA BAA 신청

부록 A — 임상 근거 자료

항목 Effect Size 출처
Working Memory ↔ Learning r=0.43 Meta-analysis, n=7947
Emotional Intelligence ↔ Academic r=0.39 EI-AP meta-analysis 2023
Emotion Regulation training d=0.605 Aldao et al. 2010
Rumination ↔ Depression r=0.42 Nolen-Hoeksema response styles
HRV biofeedback (anxiety) d=0.70 Lehrer et al. meta-analysis
Behavioral Activation (depression) d=0.74 Dimidjian et al. 2006

부록 B — 연락 자료

버전: CNA v7.0.0
최종 업데이트: 2026-05-21
라이선스: Proprietary, Boston Neuromind LLC