K-MSR Operating Rules · API
API — 같은 엔진을 프로그램에서 쓰기
대시보드·MCP·이 HTTP API는 하나의 파이썬 엔진을 공유한다. 아래 레버·패키지·단위 표는 이 페이지가 열릴 때 GET /api/solve에서 읽어 온 값이다.
1. 엔드포인트
GET = 메타(레버 허용값·패키지·단위·출처) · POST = 계산. 인증 없음, 요청 본문 64KB 이하.
| GET /api/solve | 이 페이지의 표를 만드는 메타. scenarios · macc_modes · years · units · monetary_basis · provenance · packages · model_levers · liquidity_defaults · presets |
| POST /api/solve {package_id, overrides?} | 운영규칙 패키지(P0/P1/A/B)를 엔진 solve_package로 계산 |
| POST /api/solve {scenario, macc_mode, msr, liquidity, overrides?} | 커스텀 물량규칙·λ 경로를 level_bridge_path로 계산 |
| 오류 | 400 = 잘못된 키·범위 밖 값(메시지에 이유) · 413 = 본문 초과 · 500 = 엔진 예외. 본문은 {"error": "..."} |
2. 운영규칙 패키지
엔진 메타 로드 중…
| id | 이름 | MSR | 하한 | cap | λ 레짐 | 회랑 목표연도 | 근거 상태 |
|---|
패키지 overrides 허용 키: corridor_target_year · corridor_tech2 · corridor_target_year2 · lambda_regime · cap_scenario + 아래 세계 레버 4종. 그 외 키는 400.
3. 세계 가정 레버 (overrides)
정책이 '무엇을 약속하는가'라면 레버는 '어떤 세계에서 그러는가'. 두 POST 계약 공통.
| 키 | 허용값 / 범위 | 기본값 | 설명 |
|---|
4. 요청 예시
패키지 A · 보수적 수소가격 · 자본비용 ×1.2
curl -s -X POST https://<host>/api/solve \
-H 'Content-Type: application/json' \
-d '{"package_id": "A",
"overrides": {"h2_scenario": "conservative", "cost_multiplier": 1.2}}'커스텀 물량규칙 · λ 고정
curl -s -X POST https://<host>/api/solve \
-H 'Content-Type: application/json' \
-d '{"scenario": "base", "macc_mode": "step",
"msr": {"rho": 0.12, "theta_plus_Mt": 60, "theta_minus_Mt": 20, "release_Mt": 10, "cancel": 0},
"liquidity": {"lam_0": 0.575, "lam_terminal": 0.575, "ramp_years": 0},
"overrides": {"elec_scenario": "conservative"}}'5. 응답 필드
필드명 접미사가 단위다: _Mt, _trillion, _pct. 접미사 없는 가격은 원/tCO₂.
패키지 응답
| meta.package / meta.years / meta.solver | 패키지 메타 · 연도 · 솔버 상태(fp_converged, fp_mode, infeasible_ceiling) |
| activation_headline | 헤드라인 기술별 문턱 도달 연도 (null = 2040까지 미도달) |
| defended_all · min_headroom · max_drawdown | 전 연도 하한 방어 여부 · 최소 방어여유(비율) · peak-to-trough 낙폭 |
| cum_intake_Mt · cum_release_Mt · cum_required_withholding_Mt | 흡수·방출·필요보류 누계 (Mt) |
| cum_scheduled_auction_value_trillion · cum_conditional_net_auction_revenue_trillion | 예정 경매총가치 · 조건부 순수입 (조원, 비할인 단순합) |
| cum_domestic_abatement_resource_cost_trillion · npv_… | 국내 MACC 자원비용 단순합 · r 할인 현재가치 |
| quantity_closure_status · implied_borrowing_requirement_Mt · terminal_surplus_Mt | 수량폐쇄 진단 (표시가격을 물량원장에 재대입) |
| path[] | 연도별 행: kau, kau_prefloor, floor, defended, headroom, static, hotelling, lambda, intake_Mt, release_Mt, bank_Mt, … (필드명 = 단위 접미사) |
커스텀 응답
| meta.solver | 고정점 수렴 여부 · exact/cesaro · 상한 도달 여부 |
| path[] | 연도별 행: static(λ=0), hotelling(λ=1), kau_realized(레벨-브리지), lambda, intake_Mt, release_Mt, bank_Mt, eua |
6. 단위 · 화폐 기준 · 출처
모든 응답의 meta에 같은 내용이 실린다.
엔진 메타 로드 중…
7. MCP로 쓰기 (Claude)
같은 엔진을 Claude 도구로. 표준 라이브러리 + numpy만 필요.
{"mcpServers": {"kets": {"command": "python3",
"args": ["/abs/path/kets-outlook/mcp/server.py"]}}}도구: list_packages · solve_package · solve_custom · scenario_grid(조합 ≤64) · list_data_sheets · get_data_sheet · list_runs · get_run. 상세는 저장소의 mcp/README.md.
8. 해석 경계
- 표시가격은 정태–제약 Hotelling 사이의 λ 레벨-브리지다. 완전 재청산 행태균형이 아니다 (
state_reclearing_gap_Mt가 0이 아니면). - 원화 경로에 물가지수·디플레이터가 없다. 실질/명목을 식별하지 않는다.
- A의 필요보류·조건부 순수입은 경매 수요곡선에서 추정한 유찰 예측이 아니라 회계값이다.
- 헤드라인 2기술(H₂-DRI·e-NCC)은 에너지가격 채널만 타므로
tech_scenario에 반응하지 않는다.