이것은 Hacktoberfest 오픈소스 AI 챌린지 주간 1: 풀밭에 발을 디디기(Touch Grass) 제출물입니다.

🎬 배경 이야기

제가 만든 것

대부분의 사람들은 하루를 화면만 바라보며 보내고, "밖에 더 많이 나가라"는 말은 잘 지켜지지 않습니다. TouchGrass Buddy는 사람들이 외출할 이유를 제공합니다. 사용자는 자신의 시간과 기분을 공유하고, 앱이 날씨를 확인하여 근처의 녹지 공간을 찾아줍니다. 그런 다음 그곳에서 완료해야 할 작은 미션을 하나 주고, 실제로 수행했음을 증명하는 사진을 요청합니다.

TouchGrass Buddy는 사용자에게 짧은 야외 미션을 제공하는 웹 애플리케이션입니다. 사용자는 지도상의 장소를 선택하고, 시간, 에너지, 기분, 그룹 및 지형적 요구 사항을 설정하며, 새 관찰, 사진 촬영, 산책 또는 스케치와 같은 관심사(또는 직접 작성)를 선택합니다. 앱은 날씨를 확인하고 핀 주변의 녹지 공간을 찾아내어 이를 몇 가지 구체적인 단계, 작은 보물찾기(scavenger hunt), 그리고 사진 챌린지로 변환합니다. 이후 사용자가 사진을 업로드하면, 완료된 미션들은 경험치(XP), 연속 기록(streak) 및 배지가 있는 일지에 저장됩니다.

TouchGrass Buddy home page with a short introduction, a Plan a Mission button and a three-step guide

AI-generated illustration of a hand holding a phone with a nature app on a sunny park path

코드

GitHub logo vinit-tech-source / touchgrass-buddy

🌿 TouchGrass Buddy 3.0

로컬 우선형 아웃도어 동반자 및 게임화된 현장 일지

스크린 시간을 줄이고, 자연과 다시 연결하며, AI 기반의 신체적 미션을 통해 현실 세계를 탐험하세요.

📖 개요 (Overview)

TouchGrass Buddy는 현대의 화면 피로(screen fatigue) 문제를 해결하기 위해 설계된 프라이버시 중심의 단일 페이지 애플리케이션(Single-Page Application, SPA)입니다. 단순히 휴식을 취하라고 알려주는 대신, 사용자의 정확한 동네, 현재 실시간 날씨, 에너지 수준, 개인적인 관심사에 맞춰 상황 인식형 야외 마이크로 어드벤처를 생성해 줍니다.

애플리케이션의 모든 측면은 컴퓨터에서 100% 로컬로 실행됩니다:

클라우드 AI API 비용 제로: 전적으로 Ollama를 통한 로컬 오픈 웨이트 모델(open-weight models)에 의해 구동됩니다 (미션 생성을 위한 llama3.2:3b 및 사진 검증을 위한 moondream).
완벽한 프라이버시: 사용자의 GPS 좌표, 건강 에너지 수준, 개인 일지 기록, 카메라 사진은 기기를 벗어나지 않습니다.
현대적인 야외 필드 저널 UI: 고성능 Vanilla JavaScript, CSS 커스텀 속성(custom properties), Leaflet 지도로 구축된 유기적이고 숲속 밤 같은 디자인 미학 (AllTrails와 Duolingo의 만남).

✨ 주요 기능 (Key Features)

…

GitHub에서 보기

데모 (Demo)

구축 방법 (How I Built It)

가장 큰 디자인 결정은 사실 정보와 글쓰기를 분리하는 것이었습니다. 코드는 사실(실시간 날씨, 일출 시간, OpenStreetMap 및 Wikipedia의 실제 장소)을 가져오고, 모델은 이를 미션으로 변환할 뿐입니다. 모델에게는 가상의 장소를 만들지 않도록 지시합니다.

미션 작성 (Mission writing): Ollama를 통해 로컬에서 실행되는 Llama 3.2 (3B) 모델을 사용합니다. 백엔드는 구조화된 JSON을 요청하고, 이를 검증하며, 출력이 유효하지 않으면 재시도하고, 모델이 사용할 수 없을 경우 기본 미션으로 대체됩니다.
사진 확인 (Photo check): Ollama를 통해 Moondream 모델이 업로드된 사진과 사진 챌린지를 비교하여 신뢰 점수가 포함된 AI 검사 결과를 반환합니다. 이 모델은 작고 틀릴 수 있으므로, 앱에서는 이를 보장(guarantee)이 아닌 검사(check)라고 부릅니다.
백엔드 (Backend): FastAPI (Python).
데이터 (Data): 날씨는 Open-Meteo를 사용하고, 장소 및 사진 데이터는 OpenStreetMap Overpass와 Wikipedia에서 가져오며, 인터랙티브 지도는 Leaflet을 사용합니다.
프론트엔드 (Frontend): PWA(Progressive Web App)로 설정된 바닐라 JavaScript의 싱글 페이지 앱입니다. 진행 상황과 일지 기록은 사용자 자신의 장치에 있는 브라우저의 localStorage에 저장됩니다.
테스트 (Tests): 제가 마지막으로 실행했을 때 모두 통과한 19개의 자동화된 단위 및 통합 테스트가 있습니다.

저는 AI 코딩 에이전트(Antigravity)를 사용하여 코드 작성에 도움을 받았고, 그 결과를 직접 테스트하고 편집했습니다.

오픈 혁신은 왜 중요한가?

오픈 모델 덕분에 저는 AI를 제 자신의 기기에 유지할 수 있습니다. 저의 메모와 사진은 AI 제공업체로 전송되지 않으며, 미션당 비용이 들지 않고, 원할 때마다 다른 모델로 교체할 수 있습니다. 폐쇄형 API(closed API)였다면 이 세 가지가 모두 더 어려웠을 것입니다.

정확히 말하자면: 로컬에서 실행되는 것은 AI뿐입니다. 날씨, 장소 데이터 및 지도 타일은 여전히 온라인 서비스에서 오기 때문에, 앱이 완전히 오프라인 상태는 아닙니다.

제가 테스트한 것과 잘못된 점들

저는 노트북과 휴대폰을 들고 동네와 근처 공원을 돌아보는 25분간의 테스트 산책을 했습니다.

생성된 미션:

동네 공원으로 걸어가서, 나무가 우거진 곳 근처에서 심호흡 5번을 하고, 물결 모양이거나 독특한 가장자리를 가진 나뭇잎을 찾아 사진으로 찍으세요.

책상에 앉아 있을 때는 결코 보지 못했던 세 가지 실제 문제가 외부 환경에서 발생했습니다:

위치 버튼이 혼란스러웠습니다. 처음에는 검색창 옆에 단순히 조준점 아이콘만 있었습니다. 밖에 서서 이 버튼을 누르는 것이 GPS를 가져오는 것인지 아니면 멈춘 것인지 알 수 없었습니다. 저는 이를 상태가 표시되는 '내 위치 사용(Use My Location)' 레이블이 붙은 버튼으로 교체했습니다. 이 버튼은 현재 'GPS 감지 중...' 및 이후 '위치 발견'과 같은 상태를 보여줍니다.
장소 검색의 신뢰도가 낮았습니다. 공개 OpenStreetMap Overpass 서버는 밀집 지역이나 교외 지역에서 자주 시간 초과가 발생하거나 아무것도 반환하지 않아, 길거리에 서 있는 사람도 빈 목록을 받을 수 있었습니다. 저는 대체 미러 서버와 Wikipedia GeoSearch 조회를 추가하여, 주 서버가 느릴 때도 앱이 주변 랜드마크를 제안할 수 있도록 했습니다.
사진 확인 속도가 느렸습니다. 전체 해상도의 카메라 사진을 Moondream에 전송하는 데 노트북에서 거의 20초가 걸렸고, 햇볕 아래 스피너(로딩 표시)를 기다리는 것은 답답했습니다. 저는 대체 기능을 추가했습니다. 비전 모델이 너무 오래 걸리거나 작동하지 않는 경우, 앱은 사진을 받아들이고 다음 단계로 넘어갑니다. 단점은 사진 확인 과정을 건너뛸 수 있다는 것이므로, 이는 증명이 아니라 가벼운 '격려'에 불과합니다.

다음에 개선할 점 (What I'd Improve Next)

'공원 전용(Parks Only)' 모드: 주변 장소를 공원, 자연 보호 구역, 트레일로 제한하는 토글 기능입니다. 카페나 도시 지역은 숨겨서 조용한 산책을 원하는 사람들을 위한 것입니다. 이는 테스트 중 제가 보았던 혼합된 장소 목록에 대한 답변입니다.
비전 모델용 작은 사진: 카메라 사진을 Moondream으로 보내기 전에 브라우저에서 압축합니다(예: 512x512). 목표는 제가 본 약 20초보다 훨씬 짧은 대기 시간을 확보하는 것이지만, 아직 새로운 시간을 측정하지는 못했습니다.
소형 모델 비교: Llama 3.2 3B를 Gemma 2 2B, Phi 3.5 Mini, Qwen 2.5 3B와 같은 다른 소형 모델과 임무 품질, 속도, 노트북 배터리 사용량 측면에서 테스트합니다.
오디오 산책 모드: 이어버드를 통해 단계별 내용을 음성으로 읽어주는 텍스트-음성 변환(text-to-speech) 옵션입니다. 이를 통해 휴대폰을 주머니에 넣고 다닐 수 있습니다.

이 앱의 가장 좋은 버전은 당신이 2분 후에 닫는 버전입니다. 🌿

TouchGrass Buddy: 야외 활동을 위한 작은 동기 부여를 제공하는 로컬 AI

요약

핵심 포인트