llm-quota-guard

LLM 호출 비용(토큰) 한도를 '예약 → 확정/반환' 방식으로 관리하는 TypeScript 라이브러리입니다. 외부 의존성이 없고 MIT 라이선스입니다. ■ 어떤 문제를 다루나요 단순한 카운터('한도 확인 → 호출 → 사용량 더하기')는 두 가지 상황에서 틀어집니다. 1) 동시 요청: 한도 100, 호출당 예상 30으로 10건을 동시에 보내면 모두 확인을 통과해 300이 사용됩니다. 2) 실패한 호출: 선차감 방식은 실패해도 돌려주지 않아서, 실패한 4건이 한도 100짜리 예산에서 120을 소진합니다. 위 숫자는 저장소의 `npm run example`로 재현됩니다. 실제 API 키는 필요 없습니다. ■ 어떻게 해결하나요 - reserve(): 한도 확인과 보류(hold)를 한 번에 처리해서 동시 요청이 함께 통과하지 못합니다. - commit(actual) / release(): 실제 사용량으로 확정하거나, 실패 시 보류를 돌려줍니다. 두 번 호출해도 중복 집계되지 않습니다. - 보류는 TTL이 지나면 자동으로 해제되고, 늦게 도착한 확정도 기록됩니다. ■ 한계 (먼저 밝힙니다) - 한 프로세스, 메모리 기반입니다. 여러 인스턴스나 서버리스 환경에서는 카운터가 공유되지 않습니다. - 코드가 알려주는 값만 집계합니다. 제공사가 이미 과금한 뒤 실패한 호출은 알 수 없으니, 제공사 쪽 하드 리밋을 함께 두세요. - Node 24에서 개발·시험했습니다. 테스트 22개와 예제 스크립트가 포함되어 있습니다. ■ 링크 - 저장소: https://github.com/soda4001/llm-quota-guard - 동작 원리 설명 글(영문): https://dev.to/soda4001/two-ways-a-simple-llm-token-counter-goes-wrong-with-a-demo-you-can-run-1134 ■ AI 작성 공개 이 소개글과 저장소의 코드·테스트·문서는 AI(Claude)가 계정 소유자의 지시로 작성했으며, 사람이 직접 쓰거나 수정하지 않았습니다.