Floe-Labs/floe-guard

What is floe‑guard?

floe‑guard 는 Python 및 TypeScript용 가벼운 라이브러리로, 애플리케이션이 수행하는 모든 AI 호출(대규모 언어 모델, 음성-텍스트 변환, 텍스트-음성 변환, 전화 서비스, 기타 AI 관련 공급업체)에 대해 달러 예산을 추적하고 강제할 수 있습니다. 호출 대상이 무엇이든 예산 내에서 제어할 수 있습니다.

왜 중요한가요?

• AI 에이전트는 OpenAI, Anthropic, Gemini, 음성 STT/TTS, 전화 서비스 등 여러 서비스를 호출합니다.
• 이러한 호출은 빠르게 비용이 누적되며, 기존의 사용 제한(max_tokens, max_rpm)은 폭주하는 지출을 막지 못합니다.
• floe‑guard 는 각 호출의 실제 USD 비용을 완료 직후 기록하고, 설정한 예산을 초과할 가능성이 있는 다음 호출을 실행 전에 중단할 수 있습니다.

핵심 개념

개념	기능
BudgetGuard	금액 한도(예: BudgetGuard(limit_usd=5.00))를 지정하여 인스턴스화하는 메인 클래스입니다. check()(호출 전) 및 record()(호출 후) 메서드를 제공합니다.
하드 스톱	check() 가 다음 호출이 한도를 초과할 것으로 예측하면 BudgetExceeded를 발생시켜 호출이 공급업체에 도달하지 않습니다.
라이브 레지스트리	모든 지출은 프로세스 내부(계정 없음, 네트워크 없음)에 유지되며 JSONL로 내보낼 수 있습니다. 선택적으로 레지스트리를 Floe의 호스팅 서비스에 전송하여 "카バレ지 스코어"와 7일간의 기록을 얻을 수 있습니다.
어댑터	OpenAI, Anthropic, Gemini, CrewAI, LiteLLM, LangChain, LangGraph, Vercel AI SDK에 더해 Pipecat, LiveKit, Vapi, Retell용 음성 어댑터를 제공합니다. 자동으로 요청 전에 check()를 호출하고, 요청 후에 record()를 호출합니다.
레트 카드	라이브러리에는 내장된 비용 맵(공개 가격 스냅샷)이 포함되어 있습니다. FLOE_RATE_CARD JSON을 사용해 원하는 가격으로 가격을 오버라이드하여 계약된 가격을 반영할 수 있습니다.
도구 예약	유료 도구의 경우 reserve_tool()을 도구 실행 전에, settle_tool()을 실행 후에 호출하여 병렬 호출이 많아도 아토믹한 예산 검사를 보장할 수 있습니다.
지속성	SqliteStore를 사용하면 여러 프로세스가 동일한 일일 예산(window="utc-day")을 공유할 수 있습니다.

사용 방법 (Python 예제)

from floe_guard import BudgetGuard

guard = BudgetGuard(limit_usd=5.00)   # $5 한도

guard.check()                         # 다음 호출이 $5를 초과하면 예외 발생
response = client.chat.completions.create(  # 일반적인 LLM 호출
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
# 호출 완료 후 지출 기록
guard.record(
    model="gpt-4o",
    prompt_tokens=response.usage.prompt_tokens,
    completion_tokens=response.usage.completion_tokens,
)

호출로 인해 총 지출이 $5를 초과할 경우 guard.check()가 BudgetExceeded를 발생시켜 요청이 OpenAI에 도달하지 않습니다.

음성 호출 지원

음성 파이프라인은 STT → LLM → TTS → 전화 서비스의 여러 단계로 구성됩니다. floe‑guard는 각 턴별 어댑터를 제공하여 각 턴 전에 예산을 예약하고 턴 완료 후에 정산함으로써, 전체 음성 세션이 동일한 달러 한도 내에 머무르도록 보장합니다.

계정 없음, 텔레메트리 없음 모드

• 기본적으로 모든 작업은 로컬에서 실행됩니다(API 키 없음, 가입 없음, 외부 텔레메트리 없음).
• 선택적으로 무료 Floe 계정(1개 키)을 연결하여 카バレ지 스코어와 7일간의 지출 기록을 얻을 수 있지만, 핵심 제어는 완전히 오프라인에서 작동합니다.

즉시 실행 가능한 빠른 데모

• pip install floe-guard && floe-guard demo – $0.10 한도에서 중단되는 스텁 LLM 루프를 보여줍니다.
• floe-guard estimate gpt-4o --calls 1000 --tokens-in 800 --tokens-out 300 – 내장된 맵을 사용해 워크로드의 비용을 추정합니다.
• 음성 호출 비용 데모(examples/voice_call_cost_livekit.py) – 네트워크 호출 없이 각 단계별 비용 분해를 출력합니다.

누가 필요할까?

• 루프에 빠질 수 있는 자율 에이전트(CrewAI, LangChain 등)를 개발하는 개발자.
• 클라이언트에게 사용량 기반 청구를 하는 팀으로, 과잉 청구를 절대 피하고 싶은 사람.
• 사전 예방형 지출 가드를 원하는 사람(후속 보고서가 아니라, 사전에 제어하고 싶은 사람).

---

결론: floe‑guard는 AI 관련 API 호출의 실제 달러 비용을 측정하고, 정의한 예산을 초과하기 전에 실행을 중단할 수 있는 실용적이고 오픈소스의 가드레일입니다. 오프라인에서 작동하며 주요 LLM 및 음성 툴킷과 통합 가능하며, 자체 협상된 가격을 적용할 수 있습니다.