파일 및 라인 증거를 통해 비즈니스 질문에 답하는 오프라인 AI 에이전트 구축

지난 분기, 저는 범용 AI 챗봇에게 '어떤 제품을 먼저 재고 확보해야 할까요?'라고 물었습니다. 그리고 판매량, 재고, 고객 피드백 세 개의 CSV 내보내기를 가리켰습니다. 그러자 그것은 '잘 팔리고 있는 것 같습니다'라며 SKU-A를 자신 있게 답했습니다.

SKU-A는 괜찮았습니다. 진짜 문제는 SKU-C였습니다. 14일의 공급업체 리드 타임에 비해 재고가 6.3일밖에 남지 않았는데, 매주 100개씩 판매되고 있었습니다. 그 SKU는 10일 안에 품절될 것이며, 서비스 중단되는 모든 주마다 약 100개의 매출 손실이 발생합니다. 하지만 챗봇은 그것을 파악할 수 없었습니다. 왜냐하면 파일을 실제로 결합하지 않고 단순히 열 이름만 훑어보고 추측했기 때문입니다.

바로 이 실패를 DecisionLens가 방지하기 위해 만들어졌습니다.

DecisionLens의 기능

DecisionLens는 순수 Python 표준 라이브러리로 작성된 오프라인, 제로 의존성(zero-dependency) 의사결정 에이전트입니다. 이 에이전트는 CSV 파일 폴더를 가리키고 일반 영어로 질문을 던지면 답변합니다. 그리고 그것이 하는 모든 주장에는 증거 인용(evidence citation)이 첨부됩니다: 출처 파일, 행 번호, 필드 이름.

$ python -m decisionlens ask --data examples/ --question "Which SKU should I restock first? Why?"

DECISION: Reorder SKU-C now — it stocks out in ~6 days.
...

답변에 나타나는 숫자 중 추적할 수 없는 셀은 없습니다. 에이전트가 무언가를 증명할 수 없다면, 추측하는 대신 그렇게 말합니다.

에이전트 루프

DecisionLens는 고전적인 인식(perceive) → 추론(reason) → 설명(explain) 사이클을 실행하며, 모든 단계가 감사 가능하도록 의도적으로 작게 유지되었습니다:

PERCEIVE — 데이터 폴더의 모든 CSV 파일을 로드하고, 열 유형을 추론하며, 지표(단위, 가격, 날짜, SKU) 인덱스를 구축합니다.
INDEX — 주간 판매량, 재고 보유량, 리드 타임을 비교 가능하도록 단위를 표준화하고 기간을 조정합니다.
RETRIEVE — 질문과 인덱스를 일치시켜 모든 파일에 걸쳐 관련 행을 찾습니다.
REASON — 명시적인 산술 계산(예: days-of-cover 대 lead time)을 적용하여 의사결정 규칙을 적용하며, 추측은 절대 하지 않습니다.
EXPLAIN — 각 주장에 파일 + 행 + 필드 인용을 첨부합니다.
ACT — 수량을 포함한 구체적인 권장 조치를 내보냅니다.

이것은 다음과 같은 질문에 답할 수 있습니다: 어떤 SKU가 가장 먼저 재고 부족(stocks out) 상태가 되는지, 어떤 채널이 조용히 하락하고 있는지, 지난달 대비 무엇이 어떻게 바뀌었는지 그리고 그 이유와 함께 전체 비즈니스 개요를 제공합니다.

증거 인용의 중요성

실제 결정을 내리는 데 사용되는 에이전트에게는 '아마도 맞을 것 같다'는 수준으로는 충분하지 않습니다. 인용(citation) 설계에서 세 가지 속성이 도출됩니다:

검증 가능 (Verifiable) — 관리자는 인용된 행을 열어 몇 초 만에 모든 주장을 감사할 수 있습니다.
디버깅 가능 (Debuggable) — 에이전트가 틀렸을 때, 무엇의 행이나 규칙이 그것을 오도했는지 정확히 알 수 있습니다.
정직함 (Honest) — 에이전트는 파일에서 읽지 않은 숫자를 물리적으로 주장할 수 없습니다.

마지막 속성이 바로 일반 목적 채팅 어시스턴트들이 계속 실패하는 부분입니다.

평가 기능 포함

누구나 자신의 에이전트가 똑똑하다고 주장할 수 있기 때문에, DecisionLens는 형용사 대신 평가(eval) 스위트를 제공합니다:

$ python eval.py
PASS  restock_rule_identifies_lowest_cover_sku
PASS  restock_action_includes_quantity
...

마지막 두 가지에 주목하세요: 에이전트는 모를 때는 인정해야 하며, 테스트 스위트가 코드가 네트워크 호출을 전혀 하지 않도록 단언합니다. 이것은 공기 격리(air-gapped)된 기계에서 실행되므로, 귀하의 데이터는 방을 벗어나지 않습니다.

기술 스택 (Tech stack)

순수 Python 표준 라이브러리 (csv, argparse, datetime) — pip 설치 불필요, API 키 불필요, 클라우드 사용 안 함.
1,000줄 미만, 처음부터 끝까지 읽기 쉬움.
비기술적 이해관계자들과 결정을 공유하기 위한 HTML 보고서 출력 기능.

직접 사용해보기

저장소는 github.com/Zhiyilang/decisionlens이며 세 가지 예시 데이터셋(리테일 판매, 재고, 고객 피드백)과 전체 평가 스위트가 포함되어 있습니다. 이를 클론하고 python eval.py를 실행한 다음, 자신의 CSV 파일을 대상으로 직접 질문해 보세요.

저는 DecisionLens를 Open Agent Hackathon 2026 (Track 02: 설명 가능한 다중 소스 추론)에 참가하는 저의 작품으로 만들었습니다. 핵심 논지는 간단합니다. 자신의 작업 과정을 보여주는 에이전트가 확신에 찬 것처럼 들리는 에이전트보다 더 가치 있다는 것입니다.

만약 꾸며낸 답변으로 인해 실망한 AI 답변을 경험해 본 적이 있다면, 댓글로 당신의 이야기를 들려주세요. 다음 버전을 위한 실패 모드를 수집하고 있습니다.