이 글은 Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle에 제출하는 내용입니다.

내가 개발한 기능 (What I Built)

Shoebox는 독립 계약자(gig workers)와 프리랜서를 위한 영수증 분류기이며, 사용자의 노트북에서 완전히 실행됩니다.

만약 사용자가 Uber를 운전하거나 DoorDash로 배달을 하거나 부업으로 프리랜서를 한다면, 미국 국세청(IRS)은 그들을 소규모 사업체로 간주합니다. 주유비, 전화 요금, 프린터 잉크 한 박스 등 모든 지출이 세금 청구액을 낮출 수 있지만, 증명할 수 있어야만 가능합니다. 결국 사용자는 말 그대로 신발 상자나 구겨진 영수증 400장이 담긴 카메라 롤을 갖게 되고, 4월에는 두 가지 나쁜 선택지에 직면하게 됩니다:

1. 회계사(bookkeeper)에게 150달러에서 300달러를 지불하여 분류하게 한다.
2. 올해 구매한 모든 영수증 사진을 "무료" 경비 앱에 업로드한다.

Shoebox는 세 번째 선택지입니다. 사용자가 사진들을 폴더에 넣고 하나의 명령어를 실행합니다. 자체 기기에서 실행되는 비전 모델(vision model)이 각 영수증을 읽고, IRS Schedule C (자영업 소득세 양식)의 일치하는 항목 아래에 파일을 정리하며, 그 이유를 설명하는 문장 하나를 작성합니다. 사용자는 단일 페이지에서 결과를 검토하고, 잘못된 부분이 있으면 수정한 다음, 회계사나 세금 소프트웨어에서 사용할 수 있는 CSV 파일로 내보냅니다.

누가 지불할까요: 소득의 일부를 독립 노동자로 버는 수천만 명의 미국인들입니다. 그들은 회계사를 고용하기에는 규모가 작고, 영수증은 스타트업에게 넘기기에는 너무 개인적입니다. 저는 이를 1회 19달러로 책정할 것입니다. 이 가격이 가능한 이유는 각 영수증을 처리하는 데 비용이 들지 않기 때문입니다. 더 자세한 내용은 아래에서 다룹니다.

시연 (Demo)

여기 영수증 7장으로 구성된 샘플 Shoebox를 실행한 내용입니다:

$ python3 shoebox.py ./receipts --work "freelance graphic designer who also drives rideshare"
[1/7] reading adobe.png ... Adobe Inc. $64.85 -> 18 Office expense
[2/7] reading carwash.jpg ... MISTER CAR WASH $39.99 -> 9 Car and truck expenses
...

커피 영수증이 가장 마음에 들었습니다. 그 영수증에는 '클라이언트와 로고 수정 건에 대해 만남'이라는 메모가 인쇄되어 있었습니다. 모델은 이를 사업 식사로 처리하여 구매 내역을 기록하고, 식사에 대한 50% 한도를 적용했습니다. 또한 식료품은 공제 대상에서 제외했습니다.

검토 페이지에서는 각 영수증 사진 옆에 추출된 필드가 표시됩니다. 수정 사항을 입력할 때마다 'Schedule C' 총액이 실시간으로 업데이트되며, $0과 같은 의심스러운 항목은 주황색으로 강조 표시됩니다:

코드

GitHub logo samarthsubramanya / Hacktoberfest2026-SideHustle

🧾 Shoebox

긱 워커(gig workers)와 프리랜서를 위한 영수증 정리 도구로, 노트북에서 완전히 실행됩니다. 영수증 사진을 폴더에 드롭하기만 하면 됩니다. 로컬 비전 모델(Ollama를 통한 Qwen3-VL 8B)이 각 사진을 읽고 적절한 IRS Schedule C 항목 아래에 분류하며 그 이유를 설명합니다. 사용자는 한 페이지에서 결과를 확인하고 회계사에게 제출할 CSV 파일을 내보낼 수 있습니다.

어떤 정보도 기기를 벗어나지 않습니다. 계정 연결 없음, 업로드 없음, 영수증당 비용 없음.

실행 방법

ollama pull qwen3-vl:8b
python3 shoebox.py ./my_receipts --work "rideshare driver"

그런 다음 http://localhost:8765를 엽니다. 이상해 보이는 것이 있으면 수정하고, Looks right에 체크한 후 Export CSV를 누릅니다.

• --work는 모델에게 사용자가 어떤 일을 하는지 알려줍니다. 세차장은 운전기사에게는 사업 경비이지만 디자이너에게는 개인 비용일 수 있습니다.
• --model은 다른 Ollama 비전 모델로 교체할 수 있습니다.
• 결과는 폴더 내 shoebox.json에 이미지 해시(image hash)를 키로 캐싱되므로, 재실행 시에는 새로운 사진만 읽습니다.
• Python이 필요합니다…

파일은 두 개입니다: shoebox.py (표준 라이브러리만 사용한 약 200줄의 Python 코드이며 Pillow는 선택 사항)와 review.html (프레임워크가 없는 한 페이지). 또한, 직접 영수증을 공유하지 않고도 테스트할 수 있도록 가짜 영수증을 생성하는 make_samples.py도 있습니다.

구축 과정

모델: Qwen3-VL 8B라는 오픈 웨이트 비전 언어 모델(vision-language model)을 Ollama에서 MacBook (M5 Pro, 24 GB)에 로컬로 구동했습니다.

파이프라인:

1. Shoebox는 폴더 내의 이미지를 스캔합니다. 각 이미지에는 해시값(hashed)이 부여되어 있어, 한 번 읽은 사진은 다시 처리되지 않습니다 (같은 영수증을 두 번 넣어도 두 번 계산되지 않습니다).
2. 각 이미지는 1280px로 축소되어 Ollama의 /api/chat으로 전송되며 이때 format에 JSON 스키마가 전달됩니다. Ollama는 디코드 시점에 스키마를 강제하므로, 모델은 유효한 객체만 반환할 수 있으며 그 category는 Schedule C 항목 중 하나여야 합니다.
3. 영수증마다 결과가 shoebox.json에 저장되어 중간에 충돌이 발생해도 아무것도 잃지 않습니다.
4. 작은 표준 라이브러리 HTTP 서버를 사용하여 127.0.0.1에 바인딩하고, 리뷰 페이지와 CSV 내보내기 기능을 제공합니다.

--work 플래그가 보이는 것보다 더 중요합니다. 세차장은 차량 공유 운전자에게는 사업 경비이지만 재택근무를 하는 디자이너에게는 개인 경비일 수 있습니다. 같은 모델이라도 누구를 위해 작업하는지 알려주기 때문에 각 사람에게 맞는 올바른 답변을 제공할 수 있습니다.

작동하지 않았던 두 가지 문제와 해결 방법

1. 모델이 설명하기 전에 선택했습니다. 제가 처음에 작성한 스키마는 category가 reason보다 앞에 있었습니다. 가스 영수증의 경우, 모델은 이를 _개인적(Personal)_으로 분류한 다음, 공제 가능한 차량 비용이었다고 주장하는 이유를 작성했습니다. 출력은 왼쪽에서 오른쪽으로 생성되기 때문에, 충분히 생각하기 전에 이미 답변을 확정 지은 것입니다. 스키마에서 reason을 category보다 위로 이동시키자, 모델이 먼저 설명하고 그 후에 결정하게 되었습니다. 또한 8B 모델은 "Line 10"이 무엇을 의미하는지 즉시 알지 못하기 때문에, 각 Schedule C 항목에 대한 한 줄 설명을 프롬프트에 추가했습니다. 이 두 가지 변경 사항 덕분에 모든 7개의 샘플 영수증을 정확하게 분류할 수 있었습니다.

2. think: false는 Ollama 버전에 따라 다르게 작동합니다. Ollama 0.34에서는 사고(thinking) 기능을 끄자 Qwen3-VL이 JSON을 thinking 필드에 넣고 content를 비워두었습니다. 하지만 Ollama가 빌드 도중에 0.40으로 업데이트되면서, 모델은 어쨌든 추론을 진행했고 그 결과 제가 설정한 400 토큰 출력 제한을 JSON에 도달하기도 전에 모두 소진했습니다. 해결책은 채워져 있는 필드를 읽고 제한을 3000 토큰으로 늘리는 것입니다. 이 정도면 생각할 충분한 공간이 확보되며, 모델이 통제 불능 상태가 되는 것도 막을 수 있습니다.

두 가지 수정 사항 모두 외부 공급업체 지원 티켓이 필요하지 않았습니다. 모델과 서버가 제 컴퓨터에 있었기 때문에, 정확히 무슨 일이 일어나고 있는지 확인할 수 있었습니다.

샘플 세트 결과

솔직한 한 가지 언급을 하자면: 추론 기능을 끄자 훨씬 빨라졌는데, 모델이 전화 요금 청구서를 $0.00으로 읽은 적이 있습니다. 이것이 검토 페이지가 존재하는 이유입니다. 이 제품의 목적은 "AI가 세금을 대신 처리해 주는 것"이 아닙니다. 기계가 지루한 부분을 처리하고 사람이 확인해야 할 부분을 강조하는 30초짜리 검토 과정입니다.

오픈 이노베이션은 왜 중요한가요?

왜냐하면 1년 치 영수증은 당신 삶의 지도이기 때문입니다. 그것들은 당신이 어디를 운전했는지, 무엇을 먹었는지, 어떤 약국을 이용했는지, 그리고 언제 돈이 부족해졌는지를 보여줍니다. 이 서류 작업에 가장 도움이 필요한 사람들, 즉 한 지급액에서 다음 지급액으로 살아가는 긱 워커(gig workers)들은 비용 관리 앱들이 그 모든 것을 포기하라고 요구하는 바로 그 사람들입니다. 자체 노트북에서 실행되는 모델은 이러한 상충 관계를 제거합니다. 일회성 모델 다운로드 후에는 Shoebox가 인터넷 연결이 전혀 필요하지 않습니다.**

왜냐하면 단위 경제학(unit economics)이 영수증당 $0일 때만 작동하기 때문입니다. 클라우드 비전 API는 이미지 하나하나에 실제 비용을 청구합니다. 이것을 사용자당 수백 장의 영수증에 곱하면, 사람들이 주로 세금 시즌에 한 번 사용하는 도구에 대해 구독 모델로 밀어붙이게 됩니다. 오픈 웨이트(open weights) 덕분에 저는 이 도구를 과거 소프트웨어처럼 한 번 구매하고 소유하는 $19짜리 제품으로 판매할 수 있게 되었습니다.**

왜냐하면 제가 직접 열어서 고칠 수 있기 때문입니다. 위에서 언급한 두 가지 버그 모두 모델과 서버가 작동하는 방식에 관련된 것이었고, 저는 요청 자체에서 몇 분 만에 둘 다 수정했습니다. 폐쇄형 API를 사용했다면 프롬프트(prompt), 지원 포럼, 그리고 희망에 의존해야 했을 것입니다. 오픈 웨이트는 또한 모델을 교체하는 것이 하나의 플래그(--model)로 가능하며, 장거리 트럭 운전사나 결혼 사진작가 같은 특정 분야의 수백 장의 라벨링된 영수증으로 파인튜닝(fine-tuning) 하는 것은 엔터프라이즈 계약이 아니라 주말 프로젝트가 될 수 있다는 것을 의미합니다.**

왜냐하면 아무도 저에게 가격을 올릴 수 없기 때문입니다. 이미 Shoebox를 구매한 사람들에게는 어떠한 가격 변경이나 사용 중단 통보도 이 도구를 망가뜨릴 수 없습니다.