> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 비용 관리 및 예산 통제

> 실시간 관찰, 사전 예산 보호, 지능형 모델 라우팅을 통해 LLM 지출을 통제하세요.

# 비용 관리 및 예산 관리

Myrm은(는) 지능형 라우팅을 통해 작업 품질을 유지하면서 LLM 사용량에 과도한 비용을 지출하지 않도록 보장하는 포괄적인 다계층 비용 관리 시스템을 제공합니다.

## 예산정책

### 구성(설정 → 시스템 → 예산정책)

세 가지 독립적 차원에 걸쳐 지출 한도를 설정합니다.

| Dimension       | Scope                      | Reset                 |
| --------------- | -------------------------- | --------------------- |
| **Per-session** | Single conversation / goal | Manual or new session |
| **Daily**       | All sessions combined      | Midnight auto-reset   |
| **Per-call**    | Single LLM invocation      | Stateless             |

각 차원은 4단계 점진적인 반응을 유발합니다.

```
OK → WARNING (80%) → FINALIZATION (85%) → EXCEEDED (100%)
```

### 작동 방식

1. **경고** - 에이전트는 캐시 안전 프롬프트 삽입을 통해 예산 힌트를 받습니다. 에코 모드 활성화(압축 임계값 20% 감소)
2. **최종화** — 상담원은 최종 결과를 즉시 출력하라는 지시를 받습니다. 도구 호출이 모델 출력에서 제거됩니다.
3. **초과** — 하드 블록. 예산이 재설정되거나 확장될 때까지 더 이상 LLM 호출이 없습니다.

예산 상태는 SSE 프런트엔드 푸시 `BudgetBadge` 및 목표 상태 카드를 통해 실시간으로 표시됩니다.

## 실시간 비용 관찰 가능성

### 메시지별 표시

모든 어시스턴트 메시지에는 자세한 토큰 분석이 표시됩니다.

* **7가지 토큰 유형**: 프롬프트, 완료, 캐시, 캐시\_쓰기, 추론, 인용, 전체
* **달러 단위 비용**(캐시 절약 비율 포함)
* **모델 계층** 지표(단순/표준/추론)
* **캐시 중단 이유** 캐시 누락 발생 시 속성

### 목표 패널(활성 목표)

목표가 실행되는 동안 확장된 상태 카드에는 다음이 표시됩니다.

* **소각률** — 토큰/분 소비
* **비용률** — \$/분 지출
* **ETA** — 예산 소진 예상 시간
* **진행률 표시줄** — 소비된 예산 비율

### 이용통계 대시보드(설정 → 시스템)

다음을 갖춘 전체 분석 대시보드:

* 일일 지출 차트(7/30/365일 범위)
* 토큰/비용 분석을 통한 세션 수준 드릴다운
* 모델 분석 패널(모델당 비용)
* 시간 및 주중 분포 히트맵
* 스파크라인 추세가 포함된 에이전트별 사용량 카드
* 라우팅 분석(각 계층에서 사용된 요청 수)

### 전체 체인 회계 — 맹점 없음

스트리밍 여부와 관계없이 모든 LLM 호출이 동일한 토큰 원장에 기록됩니다.

* **통합 기록**: 스트리밍 및 비스트리밍 호출이 한 곳(어댑터 계층)에서 집계되어, 서브에이전트 파생, 동적 워크플로, 백그라운드 요약, 메모리 추출, 컨텍스트 압축, 위키 컴파일까지 모두 정확하게 귀속됩니다.
* **정직한 실패 경로**: LLM 호출 실패 시 허위 사용량을 만들지 않아 원장이 부풀지 않습니다.
* **종료 시 정확성**: `message_end` 이벤트가 추적기에서 실제 사용량을 되채워, 실행별 합계가 개별 호출 합계와 정확히 일치합니다.

호스팅/종량제 사용자에게는 "보이는 청구서가 신뢰할 수 있는 청구서"라는 뜻입니다 — 백그라운드 작업이 숨지 않으며 이중 계산도 없습니다.

## 지능형 비용 라우팅

### ComplexityRouter(자동)

Myrm은 요청을 가장 비용 효율적인 모델 계층으로 자동 라우팅합니다.

* **간단함** — 빠른 질문, 인사말 → 가장 저렴한 모델
* **표준** — 일반 작업 → 균형 모델
* **추론** — 복잡한 다단계 문제 → 프리미엄 모델

특징:

* 2단계 분류(규칙 채점 + LLM 심사위원)
* **세션 모멘텀** — 후속 메시지는 품질 저하를 방지하기 위해 대화의 최근 계층을 상속합니다.
* **페널티 피드백** — 잘못된 경로를 기록하고 향후 경로 확률을 조정합니다(24시간 감쇠).
* **최소 계층** — 재생성 요청이 자동으로 계층 에스컬레이션
* **제로 구성** — 기본적으로 모든 계정에서 활성화됩니다.

### 개인정보 보호 라우팅

민감한 콘텐츠는 PII 탐지 수준에 따라 개인 정보 보호에 적합한 모델로 자동 라우팅됩니다.

## 하위 에이전트 비용 격리

### 위임예산

각 루트 작업에는 런어웨이 하위 에이전트 생성을 방지하는 `max_descendants = 20` 가드가 있습니다. 이렇게 하면 단일 작업으로 예산을 소모하는 무제한 위임 트리를 생성할 수 없습니다.

### 루트당 예산 범위

예산 추적 범위는 루트 에이전트 실행별로 지정됩니다. 하위 에이전트 비용은 상위 예산 차원에 대해 누적되어 통합된 가시성을 제공합니다.

### 다중 에이전트 비용 비행 전

에이전트가 여러 하위 에이전트를 생성해야 하는 경우(일괄 위임, 협의회 교차 검토 또는 대안 병렬 생성) Myrm은 **실행이 시작되기 전** 총 LLM 비용을 추정합니다.

* **배치 모드** — 작업 수 × 작업별 모델 가격을 기준으로 비용 추정
* **협의회 모드** — `expert_count × (1 + cross_review_rounds) + 1`(의장 합성) LLM 호출을 고려합니다.
* **대체 모드** — 병렬 전문 에이전트 수를 기준으로 추정

예상 비용이 **\$0.50**를 초과하면 채팅에 다음 내용을 보여주는 대화형 승인 카드가 나타납니다.

* 총 예상 비용(USD)
* LLM 호출 횟수
* 남은 예산

진행을 승인하거나 작업 취소를 거부할 수 있습니다. 승인할 때까지 토큰이 소비되지 않습니다. 이를 통해 복잡한 다중 에이전트 작업으로 인한 예상치 못한 비용이 발생하는 것을 방지할 수 있습니다.

## 긴 작업 복원력

### 체크포인트 및 복구

긴 작업 중에 서버 프로세스가 중단된 경우:

1. **신호 안전 체크포인트** - 실행 중인 모든 하위 에이전트가 디스크에 체크포인트됩니다(JSON + fcntl 파일 잠금).
2. **고아 복구** — 다시 시작하면 고아 스캐너가 중단된 체크포인트를 감지하고 이벤트를 UI에 게시합니다.
3. **재개 API** — 사용자는 전체 상태 복원(메시지 + 작업 공간)을 사용하여 체크포인트에서 재개할 수 있습니다.

### 골연속가드

연속 엔진은 각 턴 전에 9개 이상의 조건을 평가합니다.

* 남은 예산 확인
* 취소/조향 토큰
* 수렴 감지
* 골 드리프트 감지(5턴마다 궤적 득점)
* 할 일별 체크포인트(각 단계 후 선택적으로 일시 중지)
* 보호된 파일 무결성 검증

## 출력 압축

CLI 도구 출력은 토큰 소비를 최소화하기 위해 지능형 규칙을 사용하여 자동으로 압축됩니다.

* 경로 중복 제거 및 요약
* 반복되는 패턴 붕괴
* 바이너리/노이즈 필터링
* 요약이 포함된 큰 출력 잘림

## 캐시 효율성을 위한 안정적인 접두사

시스템 프롬프트와 도구 스키마는 프롬프트 캐시 적중률을 최대화하기 위해 신중하게 정렬되고 표준화됩니다.

* 결정론적 도구 스키마 순서 지정(SSOT)
* 스키마 표준화(비의미적 차이 제거)
* 속성 보고를 통한 캐시 중단점 감지

## 테스트 범위

313개의 테스트를 통해 비용 관리 시스템을 검증합니다.

| Module                                          | Tests |
| ----------------------------------------------- | ----- |
| token\_economics (ledger, budget, cost engine)  | 9     |
| Checkpoint (save/resume/delete/orphan)          | 47    |
| ComplexityRouter (routing + momentum + penalty) | 70    |
| Delegation budget (spawn limits)                | 26    |
| Budget middleware (injection + strip)           | 14    |
| Goal continuation (9-step guard chain)          | 76    |
| Output compressor (CLI compression)             | 71    |