이 글은 Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass에 제출하는 내용입니다.

내가 만든 것 (What I Built)

walkie — 사용자 대신 결정을 내려주는 산책 계획기입니다. 덕분에 화면을 보는 시간을 줄이고 야외에서 더 많은 시간을 보낼 수 있습니다.

우리 대부분은 게으르서 산책을 건너뛰는 것이 아닙니다. "언제 가야 할까? 얼마나 오래? 어디로?"라는 질문이 날씨 앱 확인에 10분씩 소요되고, 그러다 밤이 되어버리기 때문입니다. walkie가 이 결정을 제거합니다. 사용자는 산책 선호도를 한 번 설정하면—시간, 길이, 속도—그 후에는 노트북에서 실행되는 작은 AI 모델이 매일의 산책을 계획합니다:

1. 오늘 예보와 일광 시간을 고려하여 시간 선택: 18:00에 비가 온다면, 자동으로 17:00로 조정합니다.
2. 알림 기능 제공: T-30분, T-15분, T-5분에 각각 명언과 함께 알림을 보냅니다. 아무것도 하지 않으면 계획이 자동 승인됩니다—기본값은 나가는 것입니다.
3. 경로 구축: 집에서 시작하여 집으로 돌아오는 루프이며, 오늘 예상 시간에 맞춰 지역의 오프라인 OpenStreetMap 추출 데이터를 기반으로 합니다.
4. 방향 음성 안내: "오른쪽으로 도세요"와 같이 걷는 속도에 맞추어 로컬 텍스트-음성 변환(text-to-speech) 파일 하나로 재생됩니다.
5. 사용 방식: 휴대폰은 집 와이파이를 통해 모든 것을 다운로드하고, OsmAnd에서 GPX 파일을 열고 오디오를 시작한 뒤, 휴대폰을 주머니에 넣습니다.

화면 사용 시간이 경험 중 가장 짧은 부분입니다: 한 번 설정하면, QR 스캔, OsmAnd 탭, 그리고 산책만 남습니다.

지난 10월 10일 야외에서 테스트했습니다. 현지 지도로 만든 1.8km 루프 코스에 대해 오후 5시 30분으로 자동 승인하고, 인용문과 함께 알림을 받고, 휴대폰이 WiFi를 통해 walk.gpx 파일을 가져왔으며 (서버 로그: GET /routes/walk.gpx 200), OsmAnd의 오프라인 내비게이션으로 전체 산책을 진행했습니다. 그 산책에서 얻은 두 가지 솔직한 발견 사항을 코드에 바로 반영했습니다. 저는 증거를 위해 화면 녹화를 해두었기 때문에, 그날은 스크린 시간이 해당되지 않았고(n/a), 신규 사용자는 아직 경로가 존재하지 않는 상태에서도 마법사(wizard)를 완료할 수 있었습니다. 이 간극이 바로 전체 시스템을 이제 단일 명령어인 make 뒤에 배치하여 설정의 모든 공백을 순서대로 채우고 오늘 산책 코스를 구축하도록 만든 이유입니다.

데모 (Demo)

make

이것이 전체 인터페이스입니다. 처음 사용 시에는 의존성을 설치하고, AI 모델을 가져오며, 해당 지역의 지도를 다운로드하고, 사용자 선호도에 대한 짧은 마법사를 열어 오늘 산책 코스를 구축한 후 QR 코드와 함께 서비스 창을 엽니다. 이후 날짜마다 같은 명령어를 실행하면 변경된 부분만 재구축합니다.

휴대폰(같은 WiFi 사용): QR을 스캔하고, walk.gpx + walk_audio.mp3를 다운로드하여 OsmAnd에 가져온 후 산책합니다.

데모 영상: 오늘 경로가 표시된 서비스 창, 알림(자동 승인 포함), 그리고 휴대폰이 WiFi를 통해 walk.gpx 파일을 가져오는 과정을 확인하세요 — 마지막에 터미널에서 GET /routes/walk.gpx 200을 주목해 주세요.

코드 (Code)

GitHub logo kenedilichi1 / walkie

walkie

사용자가 결정하는 대신, 산책 계획을 짜주는 도구입니다. 덕분에 화면에서 보내는 시간은 줄이고 야외에서 보내는 시간을 늘릴 수 있습니다.

사용자가 walkie에게 언제, 얼마나 오래, 어떻게 걷고 싶은지 알려주면 됩니다. 그 후 walkie는 매일의 산책 계획을 세워줍니다. 날씨와 일광 조건을 고려하여 최적의 시간을 정하고, 집에서부터 이어지는 산책 코스를 만들며, 이 경로를 음성 지시(spoken cues)로 변환합니다. 그런 다음 휴대폰을 주머니에 넣고 나갈 준비만 하면 됩니다.

모든 과정은 오픈소스 AI가 탑재된 사용자의 노트북에서 실행됩니다. 초기 설정 후에는 계획 수립과 산책 코스 생성 시 인터넷 연결이 필요하지 않습니다.

walkie를 이용한 하루의 작동 방식

1. 시간을 정합니다. walkie는 오늘의 일기 예보와 일광 조건을 확인하고, 노트북에서 실행되는 소형 AI 모델이 산책 시간을 결정합니다. 비나 더위가 예상되면 산책 시간이 조정됩니다.
2. 알림을 제공합니다. 출발 30분 전, 15분 전, 그리고 5분 전에 알림을 받습니다.

GitHub에서 보기

제작 과정 (How I Built It)

핵심은 외부 라이브러리를 감싼 것이 아니라, 오픈소스 구성 요소 자체입니다:

• Ollama를 통한 Llama 3.2 3B — 오늘 날짜의 입력값(제안, 날씨, 일광)을 바탕으로 오늘의 계획을 결정하는 로컬 호출 기능입니다.
• Piper — 음성 지시를 위한 로컬 텍스트-음성 변환(text-to-speech) 기능입니다.
• OSMnx + OpenStreetMap 추출 데이터 — 오프라인 경로 구축기입니다 (Geofabrik의 .pbf 파일을 한 번 스캔하여 거리 그래프를 캐시).
• 일기 예보용 Open-Meteo — 계정 필요 없이, 캐싱되며, 오프라인 대체 기능이 있습니다.

flowchart LR
    subgraph laptop["사용자 노트북"]
        walkie["walkie<br/>(CLI + windows)"]
...

노트북 크기의 모델이 할 수 있는 일에 대한 기대치를 설정하는 것이 저에게 유용한 출발점이었습니다. Ali Chherawalla의 [2026년 16GB 노트북에서 로컬 AI로 가능한 것들?](https://dev.to/alichherawalla/what-can-you-do-with-local-ai-on-a-16-gb-laptop-in-2026-4epl]이나 rainytechlab의 Ollama를 이용한 Mac 로컬 AI 실행 같은 게시글들이 그러했습니다.

가장 흥미로운 엔지니어링은 LLM 호출 자체가 아니었습니다. 바로 그것을 신뢰하지 않는 것이었습니다. 한 테스트 실행에서 요청한 21:30/30분 도보 산책이 18:00–19:30/90분으로 '계획'되는 것을 확인했습니다. 즉, 모델이 입력값에서 벗어난 것입니다. 그래서 모든 답변은 저장되기 전에 입력 제약 조건과 검증됩니다. 벗어난(drifted) 답변은 거부되고 결정론적(deterministic) 입력값이 승리합니다. 이 정확한 실패 사례의 재현은 현재 레포지토리의 증거 폴더에 회귀 테스트로 보관되어 있습니다. 파이프라인 자체는 그렇지 않으면 신선도 기반으로 작동합니다. 즉, 각 단계는 입력값이 더 최신일 때만 다시 빌드되므로, cron 항목을 매분 실행해도 비용이 들지 않습니다. 게이트(gate)는 ruff + mypy --strict + 커버리지 하한선을 가진 340개의 테스트입니다.

왜 오픈 혁신이 중요한가?

이 프로젝트에서 '오픈'은 선호 사항이 아니라 제품 요구사항 목록입니다:

• 폐쇄형 API로는 실행할 수 없는 곳에서 작동합니다. 트레일헤드 테스트(비행기 모드)에서도 여전히 계획을 세우고, 경로를 구축하며, 지침을 말해줍니다. 날씨 가져오기(weather fetch)와 Ollama 모두 실패하지만, 캐시된 입력값으로 전체 체인이 완료됩니다. 폐쇄형 API는 네트워크 호출입니다. 폐쇄형 TTS도 네트워크 호출입니다. 둘 다 '신호 없음' 상태에서 작동을 멈출 것이며, 이는 이 앱이 존재하는 바로 그 순간입니다.
• 사용자의 위치와 도보 계획은 절대 노트북을 떠나지 않습니다. 계정 없음, 원격 측정(telemetry) 없음,