LedgerLocal: 오픈 모델을 사용해 클라우드에 데이터를 전송하지 않고 프리랜서의 지출 내역 정리하기

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

제가 만든 것 (What I Built)

LedgerLocal은 인도 프리랜서를 위한 작은 Node.js CLI(Command Line Interface) 도구입니다. 사용자가 은행이나 UPI 앱에서 받은 CSV 내보내기 파일을 입력하면, 이 도구가 모든 출금액을 지출 카테고리(소프트웨어, 인터넷 및 전화, 하드웨어, 여행, 식사, 학습, 코워킹, 개인)로 분류하고 전체 지출 중 사업 관련 비용이 대략 얼마인지 알려줍니다.

제가 아는 모든 프리랜서는 세금 신고 기간에 같은 방식으로 작업을 합니다. 즉, 스프레드시트에서 몇 달간의 거래 내역을 스크롤하며 추측하는 것입니다. 회계사(bookkeeper)를 고용할 여유가 있는 사람들은 전체 은행 기록을 낯선 사람이나 온라인 앱에 맡깁니다. LedgerLocal은 사용자의 노트북에서 지루한 첫 번째 분류 작업을 수행하며, 사용자의 지출 내역 중 아무것도 외부로 전송하지 않습니다.

누가 비용을 지불할까요: 자체적으로 세금 신고를 하는 프리랜서 개발자, 디자이너, 튜터, 크리에이터입니다. 이와 같은 도구는 일회성 구매(구독이 필요 없음, 서버 유지비가 없기 때문)로 판매되거나, 회계사 서비스의 한 단계인

프리랜서의 은행 또는 UPI 내보내기(export) 파일을 열 가중치 모델(open-weight model)을 사용하여 자체 노트북에서 실행하여 지출 카테고리로 분류할 수 있습니다. 사용자의 거래 정보는 절대로 기기를 벗어나지 않습니다.

Hacktoberfest 2026 Open-Source AI Challenge, Week 2: Side Hustle에 맞춰 제작되었습니다.

실행 방법 (Run it)

Node.js 18 이상이 필요합니다.

npm install
node ledgerlocal.mjs sample_transactions.csv

첫 번째 실행 시 Xenova/all-MiniLM-L6-v2 모델(~23 MB)이 ~/.cache/ledgerlocal에 다운로드됩니다. 그 후에는 완전히 오프라인으로 실행할 수 있습니다:

node ledgerlocal.mjs my_export.csv --offline --out report.csv

CSV 파일은 date, description, amount 열을 포함해야 합니다(순서 무관). 금액은 음수일 수 있으며(차감액, debits), 긍정적인 지출로 처리됩니다.

작동 방식 (How it works)

각 지출 카테고리는 몇 가지 평범한 단어로 설명됩니다.
모델은 모든 카테고리 설명과 모든 거래 설명(transaction description)을 문장 임베딩(sentence embedding)으로 변환합니다.
각 거래는 코사인 유사도(cosine similarity)를 통해 가장 가까운 카테고리를 할당받습니다. 0.25 미만인 항목은 추측되는 대신 **검토 필요 (Needs review)**로 분류됩니다.
사용자는 라인별 CSV 파일을 얻게 됩니다...

GitHub에서 보기

실행 방법:

npm install
node ledgerlocal.mjs sample_transactions.csv
# 첫 실행 후, 완전히 오프라인으로: 
...

제작 과정 (How I Built It)

모델: all-MiniLM-L6-v2는 Apache-2.0 문장 임베딩 모델이며, Xenova에서 양자화된 ONNX 빌드(~23 MB)를 사용합니다.
런타임: CPU에서 Node.js로 모델을 실행하는 Transformers.js입니다. Python도 없고, GPU도 없고, API 키도 필요 없습니다.
방식: 각 카테고리는 짧은 평이한 언어 설명으로 구성됩니다. 모델은 카테고리와 모든 거래 설명을 임베딩하고, 각 거래는 코사인 유사도를 통해 가장 가까운 카테고리를 얻습니다. 유사도가 0.25 미만일 경우 검토 필요로 분류됩니다.

여기서는 의도적으로 생성형 모델을 사용하지 않았습니다. 분류는 매칭(matching) 문제입니다. 그리고 작은 임베딩 모델은 빠르고 저렴하며 예측 가능합니다. 즉, 같은 입력에는 항상 같은 답변이 나옵니다. 14개의 행 전체를 처리하는 데 일반 노트북에서 몇 초밖에 걸리지 않습니다.

카테고리를 변경하는 것은 단지 하나의 객체 내에서 단어를 편집하는 것과 같으므로, 사진작가는 '장비(camera gear)'를 추가하고 과외 교사는 '교재(teaching materials)'를 추가해도 아무것도 재학습할 필요가 없습니다.

오픈 혁신이 중요한 이유

이 프로젝트에서 '오픈'은 선택 사항이 아닙니다. 이 제품이 존재할 수 있는 이유입니다.

프라이버시 자체가 상품입니다. 은행 명세서는 당신이 어디에 사는지, 누구에게 돈을 지불하는지, 그리고 얼마나 벌었는지를 보여줍니다. 로컬에서 실행되는 오픈 모델을 사용하면 유일한 네트워크 요청은 일회성 모델 다운로드뿐입니다. 그 이후에는 --offline 기능으로 원격 로딩을 완전히 차단할 수 있으며, 도구는 여전히 작동합니다.
비즈니스 수학이 통합니다. 호스팅된 API를 사용할 경우, 사용자가 실행할 때마다 비용이 발생하므로 구독 모델로 유도하게 됩니다. 로컬에서 실행하면 사용자당 한계 비용(marginal cost)이 0에 가깝기 때문에, 프리랜서들이 실제로 선호하는 일회성 구매가 될 수 있습니다.
종속성이 없습니다. 만약 더 좋은 작은 오픈 모델이 출시된다면, 저는 코드 한 줄만 변경하면 됩니다. 다른 누군가가 결정한 가격 책정 변경이나 지원 중단(deprecation) 같은 것이 필요하지 않습니다.

트레이드오프는 이렇습니다. 23MB의 임베딩 모델은 대규모 호스팅 모델처럼 문맥을 이해하지 못합니다. 설명에 명시되어 있지 않다면, 특정 우버 탑승이 고객 미팅이었다는 것을 알 수 없습니다. 이것이 '검토 필요(Needs review)' 버킷이 존재하는 이유이며, 출력이

저는 이 프로젝트를 AI 코딩 에이전트(Claude Code)의 도움을 받아 제가 지시한 대로 만들었습니다. 이 에이전트가 코드를 작성하고 이 게시물을 초안했습니다. 위에 있는 데모 출력은 오프라인 실행을 포함하여 제 컴퓨터에서 실제 코드를 실행한 결과입니다.