Poller 시스템 가이드

외부 앱(Gobi, Limitless 등)의 데이터를 자동으로 Vault에 동기화하는 Poller 시스템 가이드입니다.

Poller란?

Poller는 외부 소스를 주기적으로 확인하여 새 항목을 발견하면 Vault에 파일을 생성하는 컴포넌트입니다.

외부 앱 → Poller → 파일 생성 → FileMonitor → Agent 실행

Poller vs FileSystemMonitor

Poller 타입

GobiPoller

Gobi 앱의 새 노트를 자동으로 Vault에 추가합니다.

pollers:
  gobi:
    enabled: true
    target_dir: "_Inbox_"
    poll_interval: 300  # 5분마다

동작: Gobi DB 접근 → 새 노트 검색 → Markdown 변환 → target_dir에 저장

LimitlessPoller

Limitless 앱의 대화 및 노트를 가져옵니다.

pollers:
  limitless:
    enabled: true
    target_dir: "_Inbox_"
    poll_interval: 600  # 10분마다
    api_key: "${LIMITLESS_API_KEY}"

주의: 환경 변수로 API 키 설정 필요

AppleNotesPoller

Apple Notes의 새 노트를 Vault로 동기화합니다 (macOS 전용).

pollers:
  apple_notes:
    enabled: true
    target_dir: "_Inbox_"
    poll_interval: 1800  # 30분마다

ApplePhotosPoller

Apple Photos 라이브러리에서 사진을 자동으로 Vault로 동기화합니다 (macOS 전용).

기본 설정

pollers:
  apple_photos:
    enabled: true
    target_dir: "Ingest/Photolog"
    poll_interval: 3600  # 1시간마다
    days: 7              # 최근 7일 사진

설정 옵션

고급 설정 예시

pollers:
  apple_photos:
    enabled: true
    target_dir: "Ingest/Photolog"
    poll_interval: 3600
    days: 30
    favorites_only: true
    albums:
      - "Screenshots"
      - "Travel 2025"

동작 방식

Photos.app → PhotoKit API → ApplePhotosPoller → 파일 복사 → target_dir

1. PhotoKit 접근: macOS PhotoKit 프레임워크를 통해 Photos 라이브러리 접근
2. 필터링: days, favorites_only, albums 조건으로 대상 사진 선별
3. 중복 체크: state.json의 processed_items로 이미 처리된 사진 스킵
4. 파일 복사: 원본 사진을 target_dir로 복사
5. 메타데이터 생성: 사진별 .md 파일 생성 (EXIF, 위치, 날짜 정보 포함)

출력 파일 구조

Ingest/Photolog/
├── 2025-12-30/
│   ├── IMG_1234.jpg
│   ├── IMG_1234.md        # 메타데이터
│   ├── IMG_1235.heic
│   └── IMG_1235.md
├── 2025-12-29/
│   └── ...
└── state.json

메타데이터 파일 형식

---
title: IMG_1234
created: 2025-12-30
source: Apple Photos
type: photo
location: "Seattle, WA"
camera: iPhone 15 Pro
tags:
  - photo
  - favorites
---

![[IMG_1234.jpg]]

## EXIF 정보
- **촬영일**: 2025-12-30 14:32:15
- **카메라**: iPhone 15 Pro
- **위치**: Seattle, WA (47.6062, -122.3321)
- **앨범**: Favorites, Travel 2025

권한 설정

macOS에서 Photos 라이브러리 접근을 위해 권한이 필요합니다:

1. 시스템 설정 → 개인정보 보호 및 보안 → 사진
2. Orchestrator 실행 앱 (Terminal 또는 ai4pkm) 권한 허용

# 권한 확인 (Photos 접근 시 자동 팝업)
ai4pkm -o

Agent 연동 예시

사진 동기화 후 자동으로 AI 분석을 수행하려면:

nodes:
  - type: agent
    name: Photo Analysis (PHA)
    input_path: Ingest/Photolog
    output_path: AI/PhotoAnalysis
    agent_params:
      analyze_content: true
      generate_tags: true

트러블슈팅

권한 오류

Error: Photos access denied

→ 시스템 설정에서 사진 접근 권한 확인

사진이 동기화되지 않음

No new photos found

→ days 값 확인, 해당 기간에 새 사진이 있는지 확인

HEIC 파일 호환성

• HEIC 파일은 원본 그대로 복사됨
• 필요시 ImageMagick으로 JPG 변환 가능

설정 방법

orchestrator.yaml 설정

orchestrator:
  prompts_dir: "_Settings_/Prompts"
  tasks_dir: "_Settings_/Tasks"

  pollers:
    gobi:
      enabled: true
      target_dir: "_Inbox_"
      poll_interval: 300

    limitless:
      enabled: true
      target_dir: "_Inbox_"
      poll_interval: 600
      api_key: "${LIMITLESS_API_KEY}"

    apple_notes:
      enabled: false  # 비활성화

필수 설정 항목

환경 변수 사용

민감한 정보는 환경 변수로 관리:

# 셸에서 설정
export LIMITLESS_API_KEY="your-api-key"

# orchestrator.yaml에서 참조
pollers:
  limitless:
    api_key: "${LIMITLESS_API_KEY}"

상태 관리

state.json

각 Poller는 target_dir/state.json에 상태를 저장합니다:

{
  "last_poll_time": "2025-12-24T10:30:00",
  "last_note_id": 12345,
  "processed_items": ["item1", "item2"]
}

용도:

• 중복 처리 방지
• Orchestrator 재시작 후 이어서 폴링
• 디버깅

상태 초기화

처음부터 다시 폴링하려면:

# state.json 삭제
rm _Inbox_/state.json

# Orchestrator 재시작
ai4pkm -o

동작 흐름

flowchart LR
    subgraph 외부
        EA[외부 앱]
    end

    subgraph Poller
        P[Poller] --> F[파일 생성]
        F --> S[상태 저장]
    end

    subgraph Orchestrator
        FM[FileMonitor] --> A[Agent]
    end

    EA --> P
    F --> FM

1. Poller가 외부 앱 확인
2. 새 항목 발견 → Markdown 파일 생성
3. FileMonitor가 파일 생성 감지
4. 매칭되는 Agent 실행

트러블슈팅

Poller가 시작하지 않음

✓ Loaded 0 poller(s)

확인 사항:

1. enabled: true 설정 확인
2. target_dir 필수 입력 확인
3. YAML 문법 검증

API 키 오류 (Limitless)

Error: Missing Limitless API key

해결:

export LIMITLESS_API_KEY="your-api-key"

중복 파일 생성

원인: state.json 손상 또는 삭제됨

해결:

1. Orchestrator 중지
2. state.json 확인 및 복구
3. 재시작

참조

• (0) Orchestrator 개요 - 시스템 아키텍처
• (4) Orchestrator 설정 - 설정 파일 가이드
• (5) CLI 명령어 가이드 - CLI 명령어

학습 경로