_이 글은 Hacktoberfest 오픈소스 AI 챌린지 3주차: 느리지만 꾸준하게 (Slow and Steady) 제출물입니다.

제가 만든 것

저는 매우 특정한 방식으로 게으릅니다. 일을 건너뛰는 방식이 아니라, 단 2분밖에 걸리지 않는 작업을 주말 내내 자동화해서 다시는 할 필요가 없게 만드는 방식입니다. 이 프로젝트가 바로 그것이며, 여기에 오픈 가중치(open-weight) 기반 모델을 이용해 그 '2분'짜리 작업을 수행합니다.

제가 지긋지긋해했던 루틴은 여러 가지를 확인하는 것이었습니다. 은행 앱을 열고, 전기 요금 청구서를 스크롤하고, 걸음 수를 확인하는 식입니다. 매일 아침 세 개의 앱을 켜야 했고, 매일 아침 똑같은 작은 실망감만 느꼈습니다. 놀라운 것은 없고, 그저 데이터뿐이었습니다. 저는 더 이상 무언가를 확인할 필요가 없었습니다. 데이터 자체가 스스로 확인하여 중요하다고 말할 때만 알려주기를 바랐습니다.

그래서 저는 Napper를 만들었습니다. 이는 사용자가 잠자는 동안 작동하는 오프라인 우선(offline-first)의 자율 예측 AI 에이전트입니다.

작동 방식

로컬 폴더에 CSV 파일을 넣고 잠자리에 들기만 하면 됩니다. 은행 내보내기(bank export), 스마트 미터 내보내기(smart-meter export), 피트니스 트래커, 또는 공과금 판독값 등 어떤 종류의 CSV 파일이든 상관없습니다. Napper는 새벽 3시부터 알람이 울릴 때까지 다음 작업을 수행합니다:

1. 데이터 수집 및 정규화(Ingests & Normalizes): 새 파일을 읽고, 타임스탬프와 수치 시리즈를 정규화하며, 이를 로컬 저장소에 추가합니다. 중복 데이터는 SHA-256 콘텐츠 해싱을 통해 무시됩니다.
2. 다음 달 예측(Forecasts the Next Month): Prior Labs의 오픈 웨이트 테이블 기반 파운데이션 모델인 TabPFN-3.5를 사용하여, 로컬 CPU/GPU에서 실행되며 홀드아웃 검증(holdout validation)을 통해 재귀적인 30일 예측을 생성합니다.
3. 이상 징후 스크리닝(Screens for Anomalies): 모델 프리(model-free) 워크 포워드 계절 스크리닝을 실행합니다 (오늘 날짜 대 이전 8개 동일 요일의 중앙값 비교). 이를 통해 한 주가 나쁜 데이터로 미래 비교를 오염시키는 것을 방지합니다.
4. 거래 내역 감사(Audits Transactions): 은행 거래 내역을 스캔하여 반복되는 구독료 증가(subscription creep), 가격 인상, 그리고 실수로 발생한 당일 중복 청구액을 감시합니다.
5. 아침 브리프 생성(Generates a Morning Brief): 간결한 아침 브리프를 작성합니다. 일반적으로 출처별로 두 줄 정도이며, 조용한 날에는 거의 아무것도 없으며, 텍스트 및 텍스트 음성 변환(text-to-speech) 오디오를 통해 전달됩니다.

데모 데이터에서 발견한 내용 (1,110 포인트, 오탐지율 0%)

저는 실제 스토리라인이 심어진 네 개의 합성 CSV 파일(bank, electricity, steps, water)을 생성했으며, 누구나 정확한 결과를 재현할 수 있도록 시드(seed)를 설정했습니다.

TabPFN 실행 결과 요약본 (out/latest.md):

bank next month: ~1904.17 (local model tabpfn-3.5, holdout error 2.03%).
price change: fitness first gym was $24.99/mo, now $29.99/mo (+20%); possible duplicate charge: city power light billed 2x $77.86 on 2026-09-20; water spike: 425.0 liters on 2026-10-19 (expected ~52.8 liters, +706%)

네 가지 독립적인 감지기에서 발견된 4가지 케이스:

• 헬스장 멤버십 가격 인상: 헬스장이 월 회비를 $24.99에서 $29.99로 조용히 올렸다 (+20%). 반복 청구액 감지기(recurring-charge detector)는 가맹점별로 출금 내역을 클러스터링하고, 월간 안정성을 판단하며, 가격 변동(price drift)을 플래그 지정한다.
• 이중 청구: 전력 회사가 같은 날짜에 정확히 동일한 금액($77.86 x2 on 2026-09-20)으로 실수로 두 번 청구했다. 중복 감지기(duplicate detector)는 복잡한 머신러닝(ML)을 필요로 하지 않고도 동일 가맹점에서 같은 날짜에 발생한 동일 금액을 격리한다.
• 3일간의 전기 사용량 급증: 9월에 262%의 전력 급증이 있었다 (예상치 15.95 kWh 대비 57.70 kWh). 계절성 스크린(seasonal screen)은 386일의 기록 중 3개의 급증 일자를 오탐지 없이 모두 플래그 지정했다.
• 수도관 파열: 10월 19일에 치명적인 급증이 발생하여 물 사용량이 예상 기준치인 52.8 리터 대비 425.0 리터/일로 급증했다 (+706%). 누수(plumbing burst)를 첫날 포착하는 것은 공과금 청구서에서 수백 달러를 절약하고 수천 달러의 주택 침수 피해를 예방한다.
• 잊고 있던 구독 서비스: 감사 테이블(audit table)에서 Napper가 Streamly라는 서비스를 발견했다. 월 $9.99, 13개월간 운영되었으며, 3월 이후 사용하지 않았지만 조용히 청구되고 있었다.

데모 (Demo)

• 🌐 실시간 인터랙티브 대시보드 (GitHub Pages)
• 🎬 직접 비디오 링크:

대시보드 및 오디오 브리프 기능:

• 오디오 아침 브리핑(Audio Morning Brief): 통합 웹 음성 API(Web Speech API)를 사용하여 아침 일과 예측을 소리 내어 읽어주며, 버튼 클릭 시 들을 수 있습니다 (🔊 Listen to Brief).
• 예측 시계열 스튜디오(Predictive Time-Series Studio): 대화형 Chart.js 비주얼라이저가 관찰된 기록, 30일 TabPFN 예측 지평(forecast horizons), 그리고 빨간색으로 표시되는 격리된 이상 징후 마커를 렌더링합니다.
• 활성 데이터셋 스튜디오(Active Datasets Studio): 데이터셋별 세밀한 제어 기능([⚡ Analyze])을 제공하며, 단일 파일 분석, 배치 선택, [📈 Studio]를 통한 즉각적인 차트 전환이 가능합니다.
• 드래그 앤 드롭 수집(Drag-and-Drop Ingestion): CSV 파일을 브라우저에 직접 드롭하여 터미널을 건드리지 않고도 자동 해시(auto-hash), 구문 분석(parse) 및 처리 대기열에 추가할 수 있습니다.
• Sentry 추적 폭포수(Sentry Trace Waterfall): $0.00의 측정 비용으로 모든 분산 파이프라인 스팬을 시각적으로 검증합니다.

코드

GitHub logo ANSUJKMEHER / Napper

당신이 잠자는 동안 작동하는 오프라인 우선 AI 에이전트입니다. TabPFN-3.5 기반 모델과 로컬 Sentry 추적 기능을 활용하며, 비용은 $0.00입니다. Hacktoberfest 2026을 위해 제작되었습니다.

Napper

당신이 잠자는 동안 작동하는 에이전트입니다. 폴더에 CSV를 드롭하고 잠자리에 들기만 하세요. 아침이 되면 무엇이 다가오는지, 그리고 무엇이 이상한지 알려주는 두 줄의 요약본을 받게 됩니다. 예측은 TabPFN-3.5(개방형 가중치, 로컬, $0)에서 나옵니다. 이 요약본은 로컬 Gemma 모델에 의해 작성됩니다. 사용자의 데이터는 절대 기기를 벗어나지 않으며, 전체 과정이 비행기 모드에서도 실행됩니다.

Hacktoberfest 2026 DEV Challenge Week 3: 느리고 꾸준하게 (#hf26challenge, #devchallenge)를 위해 제작되었습니다.

왜 존재하는가

저는 당신이 자동화하는 방식으로 게으릅니다. 매일 아침 은행 계좌, 전기 요금 청구서, 걸음 수를 확인하기 위해 세 개의 앱을 열어야 하는 것이 지겨웠습니다. 그래서 Napper는 해당 앱들이 내보내는 CSV 파일을 감시하고, 저는 아무것도 할 필요가 없습니다.

게으른 부분: Napper는 질문에 답하지 않습니다. 스케줄에 따라 밤새 실행되며, 원하는 만큼의 시간을 사용합니다…

GitHub에서 보기

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

• GitHub Repository: https://github.com/ANSUJKMEHER/Napper

빠른 시작 (60초 만에 직접 실행하기)

git clone https://github.com/ANSUJKMEHER/Napper.git
cd Napper
python -m venv .venv
...

구축 과정

Napper는 로컬 오픈 웨이트(open-weight) 파운데이션 모델과 개인 정보 보호 기능을 갖춘 관측 가능성(observability)을 중심으로 설계된 오프라인 에이전트 파이프라인입니다:

1. TabPFN-3.5 파운데이션 모델 (Prior Labs)

취약한 고전 통계적 ARIMA 휴리스틱 또는 표 형식의 숫자를 환각(hallucinate)하는 클라우드 LLM에 의존하기보다는, Napper는 예측 엔진으로 TabPFN-3.5를 사용합니다. TabPFN은 합성된 표형 데이터셋을 기반으로 훈련된 인컨텍스트 러닝 트랜스포머(in-context learning transformer)로, 추론 시 그래디언트 디센트(gradient descent) 없이 제로샷 회귀(zero-shot regression)를 수행합니다.

Napper는 지연 특성(lag features) (1, 2, 7, 14, 30 기간), 달력 특성(요일, 월일, 추세)을 생성하고, 학습 이력을 TabPFN에 적합시킨 후 재귀적 원-스텝 자기회귀(recursive one-step autoregression)를 통해 30일 예측 지평선(forecast horizons)을 생성합니다:

from tabpfn import TabPFNRegressor

reg = TabPFNRegressor(device="auto")
...

2. Sentry AI 에이전트 트레이싱 (0.00 측정 관측 가능성)

대부분의 AI 에이전트 트레이싱 도구는 비용이 많이 드는 클라우드 API 호출을 모니터링합니다. Napper는 **Sentry AI 에이전트 분산 추적(Distributed Tracing)**을 통합하여 페이로드에 개인 식별 정보(PII)가 전혀 없는 상태로 로컬 실행을 추적합니다:

• 루트 스팬 (Root Span): napper.overnight_run (op="ai.agent")은 종단 간(end-to-end) 런타임을 추적합니다.
• 툴 스팬 (Tool Spans): ai.tool.ingest, ai.tool.recurring, ai.tool.duplicate, 그리고 ai.tool.anomaly_screen은 모듈별 지연 시간 및 감지 횟수를 기록합니다.
• 모델 스팬 (Model Span): ai.model.tabpfn은 데이터셋 모양(dataset shapes), 홀아웃 WMAPE, 추론 타이밍을 기록합니다.
• 제로 비용 측정: 모든 스팬은 명시적으로 ai.cost = 0.0 태그를 지정하고 ai_cost_usd = 0.00을 기록합니다. 이는 개인 식별 정보가 전송되지 않은(zero PII transmitted) 상태에서 로컬 실리콘 전체에 걸친 완전한 분산 추적 폭포수(distributed trace waterfalls)를 증명합니다.

3. 모델 프리 계절성 이상 감지 (Model-Free Seasonal Anomaly Screen)

파운데이션 모델은 미래를 예측하지만, 최근의 이상 징후 스크리닝(anomaly screening)에는 강력한 비모수 중앙값 필터(non-parametric median filter)가 사용됩니다:

def seasonal_expected(values, i, period_lag=7):
    # Median of previous 8 same-weekdays: one bad week never poisons the baseline
    pts = [values[i - period_lag * k] for k in range(1, 9) if i - period_lag * k >= 0]
...

4. 이중 속도 실행 엔진 (Dual-Speed Execution Engine)

• Nap 모드 (~2초): 즉각적인 CLI 테스트 및 빠른 UI 반복을 위한 경량 기준선(Lightweight baseline).
• Deep Sleep 모드 (~373초): 사용자가 잠자는 동안 밤새 실행되도록 설계된 완전한 TabPFN-3.5 파운데이션 모델 실행("느리지만 꾸준하게").

개방형 혁신은 왜 중요한가? (Why Does Open Innovation Matter?)

이 프롬프트는 어떤 상황에서 오픈 기반 접근 방식(open-based approach)이 폐쇄적인 방식보다 더 잘 작동했는지 묻습니다. 우리는 동일한 데이터셋(experiments/hare_measure.py, 아티팩트는 data/hare/run.json에 위치)을 사용하여 Napper의 로컬 TabPFN-3.5와 폐쇄형 GPT-4o-mini 제로샷 프롬프트를 비교하는 재현 가능한 일대일 벤치마크를 실행했습니다:

여기서 오픈이 승리하는 이유:

1. 금융 개인 정보 보호: 은행 거래 내역은 개인의 자서전과 같습니다. 개인 금융 출금액을 상업용 클라우드 API로 전송하는 것은 불가능합니다(non-starter). 오픈 모델은 사용자의 금융 생활이 기기를 벗어나지 않음을 의미합니다.
2. 표 형식 정밀도 vs. LLM 환각 현상: 프롬프트를 받은 LLM은 월별 날짜 및 달력 산술에 어려움을 겪으며, 165.45%의 오류를 발생시킵니다. TabPFN은 표 형식 데이터(tabular priors)에 특화하여 사전 학습되었기 때문에 GPT-4o-mini보다 약 3배 더 뛰어납니다.
3. 제로 재발 비용: 폐쇄형 API는 매일 밤 영원히 사용자에게 비용을 청구합니다. 오픈 가중치(open weights)는 사용자가 이미 소유한 일반 소비자용 노트북에서 $0.00으로 실행됩니다.

나의 에이전트 세션 (My Agent Session)

Napper는 자율 에이전트 워크플로우와 체계적인 계획을 염두에 두고 설계되고 개발되었습니다.

• 아키텍처 및 진행 상황 추적(Architecture & Progress Tracking): PLAN.md와 context.md에 문서화되어 있습니다.
• 검증된 테스트 스위트(Verified Test Suite): 수집 데이터 중복 제거(ingestion deduplication), 이상 징후 계산(anomaly math), 반복 청구 클러스터링(recurring charge clustering), API 계약 충실도(API contract fidelity)를 검증하는 16개의 자동화 단위 테스트(tests/test_server.py).
• 재현 가능한 실험(Reproducible Experiments): TabPFN과 클라우드 API를 비교하는 전체 벤치마크 스크립트와 원본 JSON 실행 결과는 experiments/hare_measure.py 및 data/hare/run.json에 게시되어 있습니다.

게으른 보상 (The Lazy Payoff)

이 콘테스트는 절약된 노력(effort saved)을 묻습니다. 다음은 Napper가 이러한 상황 중 하나를 감지할 때 각 발견이 가치 있는 산술 계산입니다:

• 정신적 세금 절감 (Mental Tax Saved): 매일 아침 3개의 앱을 확인하는 것은 약 2분의 스크롤 시간이 소요됩니다. 10초 분량의 요약본(brief)을 읽는 것은 월별 약 1.5시간의 마찰(friction)을 절약해 줍니다.
• 경제적 가치 (Economic Value, 연간 $948+ 보호):
  • 수도관 파열 감지: 첫날 감지된 +706% 급증은 수백 달러 상당의 공과금 청구서와 수천 달러 상당의 주택 침수 피해를 예방합니다($450+ 절약).
  • 가격 인상 방어: 헬스장의 조용한 월 $5 인상분을 감지했습니다(연간 $60 절약).
  • 중복 청구 방어: 즉시 $77.86의 이중 전력 청구를 감지했습니다($77.86 회수).
  • SaaS 수수료 제로: 일반적인 상용 SaaS 이상 징후 및 시계열 모니터링 도구는 월 약 $30(연간 $360 절약)가 들지만, Napper는 $0.00입니다.

솔직한 한계점 및 고지 사항 (Honest Limitations & Disclosures):

• 하드웨어 지연 시간 (Hardware Latency): 테스트 노트북(AMD Ryzen 5 5625U CPU, 16GB RAM)에서 다중 시리즈 TabPFN-3.5 추론은 약 6분(약 373초, "느리지만 꾸준함")이 걸립니다. NVIDIA GPU에서는 몇 초 만에 실행됩니다.
• 라이선싱 (Licensing): TabPFN-3.5 가중치(weights)는 비상업적 연구 라이선스 하에 공개되었습니다.
• Gemma 로컬 브리지 (Gemma Local Bridge): 녹화된 데모는 결정론적 요약본 작성기(deterministic brief writer)를 실행합니다. Gemma 브리지는 napper/digest.py에 구현되어 있으며, 단위 테스트가 완료되었고, Ollama가 실행될 때 자동으로 활성화됩니다.

상 카테고리