TL;DR

  • KORA Doctor는 AUDR JSON/JSONL 추적 데이터를 분석해 제거·캐싱·결정론적 로직 대체·저렴한 모델 전환을 고려할 만한 LLM 호출을 찾는 오픈소스 CLI임.
  • v0은 중복 호출, 실행 간 재사용, 결정론적 처리, 소형 모델 전환, 오케스트레이션 오버헤드를 간단한 휴리스틱으로 탐지함.
  • AUDR v1.0.0은 프롬프트 내용과 비밀 정보를 기록하지 않으므로, 결과는 확정 판정이 아닌 후보이며 절감액도 시나리오 추정치임.
  • 비용 추정은 여러 규칙이 한 호출에 적용되면 가장 큰 비율 하나만 반영하며, cost.total_cost가 있을 때만 계산하고 통화를 임의 변환하지 않음.
  • 독립 실행형 도구로 런타임 의존성이 없고, 현재 에이전트를 수정하거나 트래픽을 자동으로 재라우팅하지 않음.

KORA Doctor

  • KORA Doctor는 AI 에이전트가 실행한 작업과 비용을 확인하는 AUDR의 다음 단계로, 모든 추론이 필요했는지 묻는 소규모 오픈소스 CLI임.
  • AUDR JSON/JSONL을 분석해 제거·캐싱·결정론적 로직 대체·저렴한 모델 전환을 검토할 호출을 표시함.
  • 대시보드, 계정, 호스팅 서비스가 필요하지 않음.

빠른 시작

  • GitHub에서 직접 설치하는 명령은 pipx install git+https://github.com/Krako-Labs/kora-doctor.git임.
  • AUDR 파일 감사 명령은 kora-doctor audit audr.jsonl임.
  • 저장소를 복제한 경우 python3 -m kora_doctor audit samples/inefficient_agent.jsonl로 실행함.
  • 기계 판독 가능한 출력은 kora-doctor audit audr.jsonl --json으로 생성함.

예시

  • 포함된 비효율 추적 데이터는 합성 데이터이며 의도적으로 병리적인 사례로 구성됨. 보고 기능을 보여주는 데모이지 벤치마크가 아니며, 일반적인 에이전트가 89%를 낭비한다는 주장이 아님.
  • 데모 추적에서 관찰된 값은 레코드 11개, 실행 2개, 모델 호출 11회, 도구 호출 0회임.
  • 관찰된 비용은 $0.1050, 잠재적으로 피할 수 있는 비용은 $0.0936(89%), 최적화 추정 비용은 $0.0114임.
  • 후보 유형별 집계는 중복·반복 호출 5건, 캐시·재사용 후보 5건, 결정론적 후보 11건, 소형 모델 후보 11건, 오케스트레이션 오버헤드 5건임.
  • 현재 전체 출력은 kora-doctor audit samples/inefficient_agent.jsonl로 확인함.

탐지 항목

  • KORA Doctor v0은 단순한 휴리스틱부터 사용함.
  • 중복·반복 추론은 한 실행 안에서 동일한 모델·리소스 및 사용량 시그니처가 반복되는 경우임.
  • 캐시·재사용 후보는 여러 실행에서 동일한 시그니처가 나타나는 경우임.
  • 결정론적 후보는 AUDR 실행 메타데이터상 분류, 라우팅, 검증, 추출, 형식화, 파싱, 정규화로 보이는 모델 호출임.
  • 소형 모델 후보는 보고된 추론 토큰이 없고 고성능 모델에서 수행된 짧은 호출임.
  • 의심스러운 오케스트레이션 오버헤드는 모델 호출이 많아 이후 호출을 살펴볼 필요가 있는 에이전트 실행임.
  • 목적은 추론 호출이 불필요했음을 증명하는 것이 아니라, 긴 추적 데이터에서 개발자가 먼저 살펴볼 호출의 범위를 좁히는 것임.

출력에 ‘후보’라고 표시하는 이유

  • AUDR v1.0.0은 프롬프트 내용이나 비밀 정보를 담지 않고 사용량·비용 텔레메트리를 기록함. 이는 보안에 유리하지만, AUDR 레코드만으로 두 모델 호출의 의미가 같았는지 또는 작업이 확실히 결정론적으로 처리될 수 있었는지 대개 증명할 수 없음을 뜻함.
  • KORA Doctor는 추적 데이터에 직접 있는 값에 관찰값, 파생 절감액에 추정값, 최적화 기회에 후보, 휴리스틱 강도에 신뢰도를 사용함.
  • 추적 데이터로 더 강한 결론을 뒷받침할 수 없을 때는 근거가 불충분하다고 표시함.
  • 절감액은 cost.total_cost가 있을 때만 계산하며, 여러 통화를 조용히 환산하지 않음.

현재 v0의 절감 가정

  • 달러 금액은 후보별 시나리오 추정치이며, 실제로 측정된 미래 청구액이 아님.
  • 중복·반복 호출은 해당 호출의 관찰 비용 100%, 캐시·재사용 후보는 70%, 결정론적 후보는 80%, 소형 모델 후보는 50%, 오케스트레이션 오버헤드 후보는 50%를 절감한다고 가정함.
  • 한 호출이 여러 규칙에 해당하면 KORA Doctor는 가장 큰 비율 하나만 적용하며 절감 추정치를 중첩하지 않음.
  • 이 기본값은 실제 추적 데이터가 쌓이면서 쉽게 검토하고 변경할 수 있도록 의도적으로 단순하게 설정됨.

AUDR 호환성

  • KORA Doctor는 현재 AUDR v1.0.0을 대상으로 하며, AUDR JSON 객체 하나, AUDR 객체의 JSON 배열, 줄마다 AUDR 객체 하나가 있는 JSONL을 입력으로 받음.
  • 분석에 필요한 핵심 필드를 확인하지만, 공식 AUDR JSON Schema 적합성 검사기를 대체하지 않음.
  • AUDR 상류 프로젝트는 현재 LiteLLM, Vercel AI SDK, Mastra, NVIDIA NeMo Relay, Merge Gateway용 어댑터와 Chargebee를 포함한 싱크를 제공함.

샘플

  • python3 -m kora_doctor audit samples/simple.jsonl, python3 -m kora_doctor audit samples/multi_step.jsonl, python3 -m kora_doctor audit samples/inefficient_agent.jsonl로 샘플을 실행함.
  • 샘플은 KORA Doctor용으로 만든 합성 AUDR 호환 추적 데이터임.
  • 비효율 추적 데이터는 여러 휴리스틱이 작동하도록 의도적으로 구성됨.

로컬 개발

  • KORA Doctor에는 런타임 의존성이 없음.
  • 가상 환경은 python3 -m venv .venv로 만들고 source .venv/bin/activate로 활성화함.
  • 편집 가능한 로컬 설치는 python3 -m pip install -e .로 수행함.
  • 테스트는 python3 -m unittest discover -s tests -v로 실행하고, 데모는 ./scripts/demo.sh로 실행함.

한계

  • 프롬프트·입력 지문이 없어 중복 및 캐시 판정은 휴리스틱임.
  • 결정론적 후보는 실행 이름과 라벨만으로 추론함.
  • 소형 모델 권고는 출력 품질을 벤치마크하지 않음.
  • 절감액 추정은 시나리오 추정치이며 절감이 보장되지 않음.
  • v0에서 KORA Doctor는 에이전트를 수정하거나 트래픽을 자동으로 재라우팅하지 않음.
  • 이는 의도된 v0 제약이며, 실제 추적 데이터에서 추가 신호가 필요하다고 드러나면 유용한 최소 신호를 추가할 계획임.

KORA와의 관계

  • KORA Doctor는 독립 실행형이며 전체 KORA 런타임이 필요하지 않음.
  • 현재 흐름은 AUDR 추적 데이터에서 KORA Doctor를 거쳐 진단으로 이어짐.
  • 사용자가 나중에 원한다면 AUDR 추적 데이터의 진단·권고를 거쳐 KORA로 자동 최적화하는 흐름을 고려함.

기여

  • 실제 AUDR 추적 데이터, 오탐, 놓친 최적화 기회가 가장 가치 있는 피드백임.
  • 기여 안내는 CONTRIBUTING.md에서 확인하거나 이슈를 열면 됨.

라이선스

  • Apache-2.0임.