TouchGrass AI: 야외 활동을 유도하는 로컬 AI 컴패니언 구축하기 🌿

스크린 사용 시간을 줄이고 현실 세계에서 더 많은 시간을 보내도록 설계된 AI 컴패니언입니다.

1. 문제점: 우리는 스크린에 너무 많은 시간을 할애하고 있다

개발자로서, 우리는 터미널, 코드 에디터, 문서, 풀 리퀘스트(pull requests)를 응시하며 몇 시간을 보냅니다. 눈이 피곤하고 마음이 휴식이 필요할 때조차도 컴퓨터에서 벗어나기가 쉽지 않습니다.

그리고 마침내 밖에 나가더라도, 종종 스크린을 가져갑니다. 알림을 확인하거나, 소셜 미디어를 스크롤하거나, 다른 앱을 엽니다.

우리는 물리적으로 야외에 있지만, 정신적으로는 여전히 온라인 상태입니다.

Hacktoberfest 2026 Week 1의 테마인 **“Touch Grass”**를 위해, 저는 무언가 다른 것을 만들고 싶었습니다. 사람들에게 화면에 더 오래 머무르도록 장려하지 않는 AI 애플리케이션이었습니다.

대신, 저는 TouchGrass AI — 기기를 치우고 주변 세상을 탐험하도록 돕는 로컬 AI 컴패니언을 구축했습니다.

2. TouchGrass AI란 무엇인가?

TouchGrass AI는 사용 가능한 여가 시간, 기분, 주변 환경, 선호 활동을 개인화된 야외 마이크로 어드벤처(micro-adventure)로 변환합니다.

또 다른 긴 대화를 생성하는 대신, 스크린에서 벗어나 기억하고 완료할 수 있는 실용적인 임무를 제공합니다.

사용자는 다음을 선택할 수 있습니다:

• 사용 가능 시간: 10분, 20분, 30분, 60분, 또는 120분.
• 기분: 스트레스 받은(Stressed), 지루한(Bored), 활기찬(Energetic), 호기심 많은(Curious), 또는 평화로운(Peaceful).
• 활동: 산책(Walking), 정원 가꾸기(Gardening), 관찰(Observation), 조류 관찰(Birdwatching), 또는 서프라이즈(Surprise).
• 환경: 동네(Neighborhood), 공원(Park), 정원(Garden), 캠퍼스(Campus), 또는 발코니(Balcony).
• 접근성 선호도: 사용자의 이동성과 편안함 요구에 맞춰 임무를 조정합니다.

생성된 각 어드벤처에는 다음이 포함됩니다:

1. 창의적인 제목과 짧은 내러티브 후크(narrative hook)를 만듭니다.
2. 명확하고 순차적인 단계 3~5가지를 구성합니다.
3. 다양한 나뭇잎 모양을 관찰하거나 새소리를 듣는 것 같은 감각적 관찰 과제를 포함합니다.
4. 사용자들에게 휴대폰을 무음으로 하고 주머니에 넣도록 장려하는, 화면이 없는 지침을 만듭니다.
5. 돌아온 후 생각해 볼 성찰 질문(reflection question)을 준비합니다.
6. 외출하기 전에 필요한 정보만 표시하여 방해 요소가 없는 활동 모드를 구현합니다.

목표는 간단합니다: AI를 사용하여 경험에서 화면이 차지하는 부분을 가장 짧게 만드는 것입니다.

3. 클라우드 API 대신 로컬 AI를 사용해야 하는 이유?

저는 프로젝트의 목적이 사람들에게 연결을 끊도록 장려하는 것이고, 개인적인 입력 정보는 사적으로 유지되어야 하므로 Ollama를 통해 Google Gemma를 선택했습니다.

설계 단계부터 보장되는 프라이버시 (Privacy by design)

사용자의 기분, 선호도, 그리고 성찰 내용은 지극히 개인적일 수 있습니다. Ollama를 통해 로컬로 추론(inference)을 실행함으로써, 애플리케이션이 오직 로컬 엔드포인트만을 사용하고 데이터를 다른 곳으로 전송하지 않는 한, TouchGrass AI는 이러한 입력 정보를 클라우드 AI 제공업체에 보내지 않고도 미션(mission)을 생성할 수 있습니다.

오프라인 기능 (Offline capability)

애플리케이션 종속성(dependencies)과 모델 가중치(model weights)를 다운로드하면, 로컬 Ollama 서비스가 사용 가능한 동안 인터넷 연결 없이 핵심적인 미션 생성 워크플로우가 작동할 수 있습니다.

이는 집에 떠나기 전이나 연결성이 좋지 않은 장소를 방문하기 전에 활동을 준비하고 싶을 때 유용합니다.

실험의 자유 (Freedom to experiment)

오픈 가중치(open-weight) 모델을 사용하면 다양한 모델로 실험해 보고, 프롬프트(prompt)를 조정하며, 애플리케이션 로직을 검사하고, 비용이 발생하는 클라우드 AI API 키가 필요하지 않은 상태에서 구축할 수 있습니다.

Gemma는 Google의 Gemma 이용 약관에 따라 배포되는 오픈 가중치 모델입니다. 해당 약관은 여전히 적용되므로, 오픈 가중치를 무제한 라이선싱과 혼동해서는 안 됩니다.

이 프로젝트에서 로컬 추론은 단순한 기술적 선택이 아닙니다. 이는 중심 아이디어를 뒷받침합니다: 즉, 기술은 사람들이 주변 세상과 다시 연결되는 것을 도와야 한다는 것입니다.

4. 제가 구축한 방법

TouchGrass AI는 Streamlit 인터페이스, 로컬 추론을 위한 Ollama, 데이터 검증을 위한 Pydantic, 그리고 진행 상황 추적을 위한 SQLite를 사용하는 모듈식 Python 아키텍처로 구성되어 있습니다.

기술 스택 (Tech stack)

• Python: 핵심 애플리케이션 로직.
• Streamlit: 사용자 인터페이스.
• Ollama: 로컬 모델 서빙.
• Google Gemma: 오픈 웨이트 언어 모델.
• Pydantic: 입력 및 출력 검증.
• SQLite: 어드벤처 기록 및 관찰 진행 상황.
• Pytest: 자동화 테스트.

아키텍처 (Architecture)

애플리케이션은 다음 흐름을 따릅니다:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/q11fnt53ny17kvpy7vt1.png)

주요 모듈 (Key modules)

app.py

사용자 선호도를 수집하고, 생성된 미션을 자연에서 영감을 받은 시각적 디자인으로 표시하며 Streamlit 인터페이스를 제공합니다.

services/ollama_service.py

모델 검색 및 생성을 포함하여 Ollama의 로컬 HTTP API와 통신합니다. 연결 실패, 누락된 모델, 시간 초과 등의 상황을 처리합니다.

services/mission_generator.py

프롬프트를 구성하고 구조화된 JSON 출력을 요청하며, JSON 페이로드를 추출하고 OutdoorMission이라는 Pydantic 모델에 따라 결과를 검증합니다.

services/progress_service.py

어드벤처 기록과 관찰 완료 사항을 SQLite에 저장합니다. 단순히 진행 상황을 꾸며내는 것이 아니라, 기록된 날짜를 기반으로 연속 일수 스트릭(consecutive-day streaks)을 계산합니다.

5. 가장 어려웠던 도전: 소규모 로컬 모델에서 신뢰할 수 있는 JSON 얻기

가장 흥미로운 도전 중 하나는 소규모 로컬 모델이 구조화되고 사용 가능한 미션 데이터를 반환하도록 만드는 것이었습니다.

모델은 답변 전에 대화형 텍스트를 생성하거나, JSON을 마크다운 코드 울타리(Markdown code fences) 안에 감싸거나, 필수 필드를 누락시키거나, 형식이 잘못된 출력을 반환할 수 있습니다.

이는 애플리케이션이 특정 구조를 기대하는 경우 문제가 됩니다.

저는 이 문제를 세 가지 계층의 보호 장치로 해결했습니다.

1. Ollama JSON 모드 (Ollama JSON mode)

생성 요청에 `

이로써 파서는 예상치 못한 표현에도 더 관대해지지만, 여전히 잘못되거나 불완전한 JSON은 실패할 수 있습니다.

3. Pydantic 유효성 검사 및 오프라인 폴백(fallback)

추출된 객체는 OutdoorMission 스키마를 기반으로 유효성 검사를 거칩니다. 만약 생성에 실패하거나 출력값이 유효성 검사를 통과할 수 없다면, 애플리케이션은 자체적으로 큐레이션한 오프라인 미션 라이브러리를 사용할 수 있습니다.

이 폴백 기능은 **“🍂 큐레이션된 오프라인 라이브러리”**로 명시되어 있어, 사용자가 로컬에서 생성된 AI 미션과 미리 정의된 미션을 구분할 수 있습니다.

이 접근 방식은 매우 중요합니다. 왜냐하면 로컬 모델이 단지 하나의 응답이 잘못되었다는 이유만으로 전체 사용자 경험을 망가뜨리도록 허용해서는 안 되기 때문입니다.

6. 테스트 및 검증

저는 신뢰성을 단순히 성공적인 시연에 의존하기보다는 프로젝트의 중요한 부분으로 다루었습니다.

자동화된 테스트 스위트는 Pytest와 목업(mocked) Ollama 엔드포인트를 사용하여, 모든 테스트마다 라이브 추론(live inference)을 요구하지 않고도 동작을 테스트합니다.

테스트 케이스는 다음을 포함합니다:

• 사용자 선호도 유효성 검사.
• 야외 미션 스키마 유효성 검사.
• 일반 텍스트 및 Markdown에서 JSON 추출.
• Ollama 연결 불가 시 폴백 동작.
• 시간 초과(timeout) 후 폴백 동작.
• 연속 일수 기록 계산.
• 기록 유지 및 당일 여러 세션 처리.

기록된 실행은 선별된 대체 라이브러리(fallback library)를 사용하지 않고 완료되었습니다.

7. TouchGrass AI 실행 방법

Python과 Ollama를 사용하여 자신의 컴퓨터에서 프로젝트를 실행할 수 있습니다.

단계 1: Ollama 설치

https://ollama.com에서 Ollama를 다운로드하여 설치하세요.

프로젝트에서 사용되는 모델을 가져옵니다 (Pull):

ollama pull gemma:2b

Ollama는 일반적으로 설치 후 백그라운드에서 실행됩니다. 서버가 이미 실행 중이라면 ollama serve로 다른 인스턴스를 시작할 필요가 없습니다.

단계 2: 저장소 복제 (Clone)

아래 URL을 실제 공개 저장소 URL로 교체하세요.

git clone YOUR_GITHUB_REPOSITORY_URL
cd touchgrass-ai

단계 3: 가상 환경 생성

Windows의 경우:

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

macOS 또는 Linux의 경우:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

단계 4: 테스트 실행

pytest tests -v

단계 5: 애플리케이션 실행

streamlit run app.py

브라우저에서 http://localhost:8501을 여세요.

선호 사항을 선택하고, 모험(adventure)을 생성하며, 단계를 암기한 후 밖으로 나가세요.

오프라인 사용의 경우, 필요한 종속성(dependencies)과 모델 가중치(model weights)가 이미 설치되고 다운로드되었는지 확인하세요.

8. 다음 계획은?

TouchGrass AI는 여러 방향으로 성장할 수 있습니다:

• 오프라인 자연 소리 풍경 (soundscapes): 비, 바람, 흐르는 물에 대한 선택적 주변 오디오.
• 인쇄 가능한 현장 노트: 화면 없이 자연 일기를 작성할 수 있는 내보내기 가능한 PDF 또는 Markdown 체크리스트.
• 계절 인식 임무 (Season-aware missions): 계절 변화와 지역적으로 관련된 환경 조건에 활동을 맞추어 조정합니다.
• 더 많은 모델 선택지: 사용자가 호환되는 다양한 로컬 모델을 구성할 수 있도록 합니다.
• 접근성 개선: 개인의 필요와 주변 환경에 맞춰 활동을 조정하는 더 많은 방법을 제공합니다.

이러한 개선 사항들은 주요 목적을 잃지 않으면서 경험을 확장할 것입니다.

9. 최종 생각

TouchGrass AI를 구축하면서 제가 중요하다고 느끼는 아이디어를 재확인했습니다. 바로 AI가 항상 기술과의 참여(engagement)를 극대화할 필요는 없다는 것입니다.

때로는 가장 유용한 애플리케이션이 노트북을 닫고, 알림들을 뒤로하고, 우리 주변의 것에 주의를 기울이도록 도와주는 것일 수 있습니다.

오픈 웨이트 모델(Open-weight models)과 로컬 추론(local inference)은 이러한 경험을 더욱 사적이고(private), 맞춤화하며, 유료 클라우드 AI 서비스에 의존하지 않고 실험하고 싶은 사람들에게 접근 가능하게 만듭니다.

최고의 AI 상호작용은 당신이 상호작용하는 것을 멈추고 탐험하기 시작하도록 영감을 주는 것일 수 있습니다. 🌱

프로젝트 링크

• GitHub 저장소: [https://github.com/Renuka-Kamani/touchgrass_ai\]

• 애플리케이션 스크린샷: [
  

  
  Uploading image
  ]

Hacktoberfest 2026 오픈 소스 AI 챌린지 — 1주차: 풀잎 밟기(Touch Grass)를 위해 제작되었습니다.