Horizon 딥다이브
— 10개 출처를 긁어 프로파일로 채점·정제하는 개인용 뉴스 레이더

1프로젝트 한 줄 요약

Horizon은 한 문장으로 "개인용 뉴스 통신사"다. 흩어진 정보원에서 글을 모으는 수집기(scraper), 같은 이야기를 합치고 중요도를 매기는 정제 파이프라인, 그리고 결과를 웹·메일·채팅으로 내보내는 배달 계층의 세 부분으로 이뤄진다.

슬로건은 "Enjoy the News itself. Leave others to Horizon" — 읽는 즐거움만 남기고 나머지 잡일은 넘기라는 뜻이다. 저자가 README에 쓴 문제의식은 이렇다. "좋은 뉴스는 흩어져 있고, 나쁜 뉴스는 끝이 없다." 그래서 Horizon은 요약기가 아니라 필터를 자처한다. AI는 노이즈를 줄이는 데 쓰고, "무엇이 볼 만한가"라는 취향 판단은 사람이 설정 파일로 남긴다.

하루치 실행은 대략 이렇게 흐른다. 아래 숫자는 파이프라인 단계 번호이고, 실제 코드에서도 src/orchestrator.py의 run() 안에 같은 순서로 주석이 달려 있다.

1. 시간창 결정   지금부터 거꾸로 24시간(time_window_hours)
2. 수집         10개 출처를 asyncio로 동시에 긁기
3. URL 병합      같은 주소를 가리키는 항목을 하나로 (트래킹 파라미터 제거 후 비교)
4. AI 분석       항목마다 프로파일 배정 + 점수 + 태그 + 한 줄 요약
5. 선별         점수 임계값 통과 → AI 의미론적 중복 제거 → 카테고리 균형 맞추기
6. 보강         살아남은 것만 웹 검색으로 배경·영향·커뮤니티 반응 덧붙이기
7. 요약·배달     언어별 마크다운 생성 → Pages·메일·웹훅·MCP

비용 구조를 이해하는 열쇠는 4번과 6번 사이의 5번이다. 값싼 채점은 전량에 돌리고, 비싼 보강(웹 검색 + 긴 생성)은 걸러낸 소수에만 돌린다. 뒤에서 자세히 본다.

2왜 주목받는가

"RSS를 읽어 GPT로 요약한다"는 주말 프로젝트는 수백 개가 있다. Horizon이 별 5.8천 개를 모은 이유는 요약이 아니라 요약 전후의 궂은일을 전부 코드로 해결했기 때문이다. 넷으로 나눠 본다.

① API 키 없이 긁을 수 있는 길을 끝까지 찾는다

대부분의 개인 프로젝트는 "Reddit API 키 발급받으세요"에서 막힌다. Horizon은 키 없이 되는 경로를 먼저 시도하고, 막히면 다음 경로로 넘어가는 방식을 출처마다 심어 뒀다. Reddit은 옛 HTML → JSON → RSS 3단, 텔레그램은 도메인 3개를 번갈아 시도하는 식이다(4장에서 상세히 다룬다). GDELT·구글뉴스·Hacker News·OSS Insight는 아예 키가 필요 없는 공개 엔드포인트만 쓴다.

② "프로파일"로 판단 기준을 파일에 고정했다

2026년 7월 31일 커밋 feat(profile): add profile-driven processing으로 들어온 구조다. 그전에는 점수 기준과 요약 지시가 코드 안 프롬프트 문자열에 박혀 있었는데, 지금은 폴더 하나가 곧 하나의 편집 방침이다.

profiles/tech-news/
├── profile.json      어떤 블록을 어떤 도구로 만들지 (구조)
├── match.md          "이 항목이 이 프로파일에 해당하는가?" 판정 지시
├── analysis.md       점수 기준 (무엇이 10점이고 무엇이 3점인가)
└── enrichment.md     배경·영향·댓글 요약을 어떻게 쓸지

기본 제공은 tech-news(기술 뉴스)·tech-blog(기술 블로그)·finance-news(금융)·ai-creator(AI 크리에이터) 4종이고, 사용자가 폴더를 추가하면 그대로 늘어난다. 출처마다 프로파일을 지정할 수도, "auto"로 두어 AI가 항목별로 어느 방침에 해당하는지 고르게 할 수도 있다.

③ 중복 제거를 두 겹으로 한다

같은 사건이 HN·Reddit·RSS에 동시에 뜨는 건 일상이다. Horizon은 기계적 병합(같은 URL — 단, 트래킹 파라미터를 벗겨 낸 뒤 비교)과 의미론적 병합(제목·태그·요약을 AI에 통째로 보여 주고 "같은 사건인 것끼리 묶어라")을 순서대로 건다. 후자에서는 버리는 쪽의 댓글 내용을 살아남는 쪽에 합쳐 넣어 정보가 사라지지 않게 한다.

④ 결과를 내보내는 길이 넷이다

브리핑 하나를 만들어 GitHub Pages 사이트(Jekyll), 자체 SMTP 뉴스레터, 웹훅(Feishu·DingTalk·Slack·Discord·범용), 그리고 MCP 서버로 동시에 내보낸다. 특히 MCP는 Claude 같은 AI 클라이언트가 브리핑을 직접 조회하게 해 준다 — 뉴스 파이프라인 자체를 AI의 도구로 노출하는 셈이다.

3기술 스택 전체 지도

Horizon은 웹 서버가 아니라 배치 파이프라인이다. 하루 한 번(또는 크론 주기마다) 실행되고 끝나는 프로그램이라, 흔한 웹 스택 대신 "긁고 → 처리하고 → 파일로 뱉는" 도구들로 채워져 있다.

런타임 · 패키징

수집 · 파싱 계층

AI · 처리 계층

출력 · 운영

4아키텍처 심화 분석 — 수집 전략이 핵심

AI 호출은 사실 어렵지 않다. 실제로 매일 돌리는 파이프라인을 무너뜨리는 건 수집 단계다 — Reddit이 차단하고, 텔레그램 도메인이 막히고, 한 출처가 죽으면 전체가 멈춘다. Horizon의 src/scrapers/는 이 문제들에 대한 구체적인 답의 모음이다. 이 장은 거기에 지면을 크게 쓴다.

4-1. 전체 구조도

구조에서 가장 중요한 결정은 [4]가 [5]보다 앞에 있다는 것이다. 채점은 전량에 하되 보강은 살아남은 소수에만 한다. 웹 검색이 붙는 보강 호출이 채점보다 훨씬 비싸기 때문에, 이 순서 하나가 토큰 비용을 몇 배 단위로 가른다.

4-2. 수집기의 계약 — 놀랄 만큼 얇다

10종이나 되는 출처를 붙였는데도 공통 인터페이스는 src/scrapers/base.py 47줄이 전부다.

class BaseScraper(ABC):
    def __init__(self, config: dict, http_client: httpx.AsyncClient):
        self.config = config
        self.client = http_client        # ← 클라이언트를 '주입받는다'

    @abstractmethod
    async def fetch(self, since: datetime) -> List[ContentItem]:
        ...

    def _generate_id(self, source_type, subtype, native_id) -> str:
        return f"{source_type}:{subtype}:{native_id}"   # 예) reddit:subreddit:1a2b3c

계약은 셋뿐이다. ① HTTP 클라이언트를 스스로 만들지 않고 주입받는다. ② fetch(since) 하나만 구현하면 된다. ③ 무엇을 긁든 ContentItem이라는 하나의 자료형으로 돌려준다.

4-3. 출처별 수집 방식 한눈에

Horizon이 지원하는 10종을 무엇으로 긁는가 기준으로 정리하면 이렇다. 인증이 필요한 건 X와 (선택적) GitHub뿐이라는 점이 눈에 띈다.

4-4. 막히면 다음 길로 — 폴백 사다리 세 가지

Horizon 수집 코드에서 가장 실전적인 부분이다. 세 사례가 각기 다른 종류의 장애에 대응한다.

4-5. 한 출처가 죽어도 브리핑은 나온다

매일 도는 파이프라인에서 제일 흔한 사고는 "출처 하나가 죽어서 전체가 실패"다. Horizon은 수집을 _fetch_with_progress()로 감싸 예외를 그 자리에서 잡고 결과 객체로 바꾼다.

try:
    items = await scraper.fetch(since)
except Exception as exc:
    return SourceFetchOutcome(source_name=name, status="failure",
                              error=f"{type(exc).__name__}: {exc}")
return SourceFetchOutcome(source_name=name,
                          status="success" if items else "empty", items=items)

그래서 asyncio.gather(*tasks)는 절대 중간에 터지지 않는다. 살아남은 출처의 항목만 모아 계속 진행하고, 실패는 보고서에 남는다. 다만 전부 실패한 경우에만 all_failed로 전체를 중단시킨다 — 빈 브리핑을 발행해 구독자에게 보내는 사고를 막는 안전장치다.

진행 상황 출력도 세심하다. 출처 안에 하위 출처가 여럿이면(예: 여러 서브레딧) _sub_source_label()이 r/LocalLLaMA·@채널명·피드 이름 순으로 라벨을 찾아 어디서 몇 건이 왔는지 분해해 보여 준다. "오늘 왜 이 출처만 0건이지?"를 로그만 보고 알 수 있다.

4-6. 중복 제거 — 무료 단계를 먼저, 유료 단계를 나중에

1단계는 URL 정규화 비교다. 핵심은 비교 전에 주소를 씻는 것.

_TRACKING_QUERY_PARAMETERS = {"_ga","dclid","fbclid","gclid","igshid",
                              "li_fat_id","mc_cid","mc_eid","msclkid",
                              "ttclid","twclid","vero_id"}
# + utm_ 으로 시작하는 모든 파라미터 제거
# + 기본 포트(80/443) 제거, 끝 슬래시 정리, 호스트 소문자화

같은 기사라도 트위터에서 온 링크엔 ?twclid=…, 뉴스레터에서 온 링크엔 ?utm_source=…가 붙는다. 이걸 벗기지 않으면 같은 기사가 서로 다른 주소로 보여 중복 제거가 통째로 무력화된다. 씻은 뒤 같은 주소로 묶이면 내용이 가장 풍부한 것만 남기고 메타데이터를 합친다.

2단계는 AI 의미론적 중복 제거다. 주소가 달라도 같은 사건인 경우 — 같은 발표를 다룬 TechCrunch 기사와 The Verge 기사 — 를 잡는다. 항목의 제목·태그·요약을 번호 매겨 한 번의 호출로 보내고, {"duplicates": [[0, 3, 7], ...]} 형태로 묶음을 받는다(항목마다 호출하는 게 아니다). 프롬프트는 "같은 제품이라도 다른 사건이면 중복이 아니다"(제미나이 출시 vs 제미나이 탈옥)라고 못 박고, 애매하면 남기는 쪽으로 기울이라고 지시한다.

[0] OpenAI announces GPT-5.5
    Tags: AI, LLM      Summary: ...
[3] GPT-5.5 발표, 컨텍스트 200만 토큰
    Tags: AI, OpenAI   Summary: ...
   ↓ AI 응답: {"duplicates": [[0, 3]]}
   ↓ 0을 남기고 3을 버리되, 3의 댓글 내용은 0에 이어붙임
0.content += "\n\n--- From reddit ---\n(레딧 댓글들)"

설계상 세 가지가 영리하다. 첫째, 점수 내림차순으로 정렬한 뒤 호출하므로 각 묶음의 첫 번째가 항상 최고점 항목이다(무엇을 남길지 AI가 고민할 필요가 없다). 둘째, 버리는 항목의 댓글을 살아남는 항목에 합쳐 커뮤니티 반응이 유실되지 않는다. 셋째, 이 비교는 같은 프로파일 안에서만 이뤄진다 — 기술 뉴스와 금융 뉴스는 애초에 서로 견주지 않는다.

그리고 AI 호출이 실패하면 그냥 원본을 반환하고 넘어간다. 중복이 조금 남는 브리핑이 브리핑이 아예 없는 것보다 낫다는 판단이다 — 4-5절의 "부분 실패는 값으로" 원칙이 여기서도 반복된다.

4-7. SSRF 방어 — 남이 준 URL을 그대로 열지 않는다

설정에서 온 웹훅 주소나 피드가 알려 준 기사 링크는 개발자가 고정해 둔 주소가 아니다. 이를 그대로 요청하면 공격자가 http://169.254.169.254/(클라우드 메타데이터) 같은 내부 주소를 넣어 서버 내부를 훔쳐보게 만들 수 있다. 7월 13일 feat(ALL): enhance security 커밋으로 src/url_security.py가 들어왔다.

[1단계] 구조 검사 (네트워크 없음)
  스킴       http/https만 허용
  자격증명    user:pass@host 형태 거부
  포트       1~65535 범위 밖 거부
  호스트      localhost · *.localhost 거부 (끝점 제거 후, 대소문자 무시)

[2단계] DNS 해석 후 IP 검사
  해석된 주소가 하나라도 사설·루프백·링크로컬·멀티캐스트·예약 대역이면 거부
  → 여러 A 레코드 중 하나만 내부 IP인 우회를 막는다

진짜 핵심은 리다이렉트 처리다. httpx의 자동 추적(follow_redirects=True)을 끄고 한 홉씩 직접 따라가며 매번 다시 검증한다. 안 그러면 겉보기엔 멀쩡한 공개 주소가 302로 내부 주소를 가리키는 순간 그대로 뚫린다.

적용 범위는 정확히 두 곳이다 — 웹훅 전송과 기사 원문 추출(trafilatura). 둘 다 "목적지를 사용자나 외부 데이터가 정한다"는 공통점이 있다. 반대로 Hacker News·GitHub API처럼 주소가 코드에 박혀 있는 호출은 이 관문을 타지 않는다 — 검증을 무조건 다 거는 게 아니라 신뢰 경계가 있는 곳에만 건 설계다.

5디렉토리 구조 해부

폴더 구조가 4장의 파이프라인 그림과 거의 1:1로 대응한다. 긁는 것은 scrapers/, 판단하는 것은 ai/, 내보내는 것은 services/다.

처음 읽는 사람에게 권하는 순서는 이렇다. ① orchestrator.py의 run() 하나만 읽으면 전체 흐름이 잡힌다(주석에 1~7단계가 번호로 달려 있다). ② scrapers/base.py 47줄로 수집기 계약을 본다. ③ 관심 있는 출처 하나(telegram.py가 짧고 재밌다)를 읽는다. ④ profiles/tech-news/analysis.md를 열어 "점수 기준이 코드가 아니라 글"이라는 걸 확인한다.

6학습 포인트

이 저장소의 가치는 "뉴스 앱"이 아니라 매일 돌아가는 수집 자동화를 어떻게 안 죽게 만드는가에 대한 사례집이라는 데 있다. 아래 일곱 개는 뉴스와 무관한 자동화에도 그대로 적용된다.

① 비동기 동시 수집 + 클라이언트 공유

출처 10곳을 순서대로 긁으면 대기 시간이 그대로 더해진다. 각 요청은 대부분 "응답을 기다리는" 시간이라(I/O 바운드), asyncio.gather로 동시에 던지면 전체 시간이 가장 느린 한 곳에 수렴한다. 핵심은 httpx.AsyncClient를 하나만 만들어 전부에 주입하는 것 — 커넥션 재사용과 타임아웃 일원화를 공짜로 얻는다.

② 폴백 사다리 — "안 되면 다음 방법"을 코드로

웹에서 데이터를 긁는 일은 언젠가 반드시 막힌다. Reddit 3단·텔레그램 도메인 3개가 보여 주는 원칙은 두 가지다. 덜 막히는 경로를 먼저 시도하고(공식 API가 항상 1순위는 아니다), 열등한 경로로 얻었음을 데이터에 기록한다("fallback": "rss"). 후자가 없으면 나중에 "왜 이 항목만 점수가 없지?"에서 헤맨다.

③ 부분 실패는 값으로, 전면 실패는 예외로

4-5절에서 본 SourceFetchOutcome 패턴. 자동 발행 시스템에서는 "조금 부족한 결과"와 "아무것도 없는 결과"를 다르게 다뤄야 한다. 전자는 내보내도 되고 후자는 멈춰야 한다. 이 구분을 코드로 명시하지 않으면, 어느 날 조용히 빈 메일이 나간다.

④ 비교하기 전에 정규화하라

URL 중복 제거의 교훈은 일반적이다. 같은 것을 같다고 판정하려면 먼저 표준형으로 씻어야 한다. Horizon은 트래킹 파라미터·기본 포트·끝 슬래시·대소문자를 정리한 뒤 비교한다. 이걸 건너뛰면 중복 제거 로직이 있어도 아무것도 안 잡힌다 — 버그가 아니라 조용한 무력화라 발견도 늦다.

⑤ 값싼 단계로 걸러낸 뒤 비싼 단계를 태워라

LLM 파이프라인 비용의 8할은 순서 문제다. Horizon은 채점(짧은 호출)을 전량에, 보강(웹 검색 + 긴 생성)을 통과한 소수에만 돌린다. 100건을 긁어 10건을 발행한다면, 보강을 앞에 두는 순간 비용이 10배다.

⑥ 판단 기준을 코드 밖으로 — 프롬프트를 파일로

프로파일 시스템의 본질은 "설정 파일 늘리기"가 아니라 변경 빈도가 다른 것을 분리한 것이다. 파이프라인 로직은 몇 달에 한 번 바뀌지만, "무엇이 중요한가"라는 기준은 매주 바뀐다. 후자를 마크다운으로 빼 두면 파이썬을 건드리지 않고, 코드 리뷰 없이, 심지어 개발자가 아닌 사람도 고칠 수 있다.

⑦ 외부에서 온 URL은 열기 전에 검증하라

RSS 주소·검색 결과처럼 내가 쓰지 않은 주소로 요청을 보내는 코드가 있다면 SSRF 검증은 선택이 아니다. 이름 검사만으로는 부족하고 DNS 해석 결과가 사설 IP인지까지 봐야 한다는 게 url_security.py의 요지다.

실습 아이디어 (읽고 끝내지 않으려면)

7하드웨어 / 시스템 요구사항

Horizon은 모델을 직접 돌리지 않고 외부 API를 호출한다(Ollama를 붙이면 로컬 모델도 가능). 그래서 머신 사양은 거의 문제가 되지 않는다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

6주를 다 채우기 어렵다면 1·3·5주차만 해도 남는 게 많다. 비동기로 동시에 긁고, 하나의 스키마로 정규화하고, 부분 실패를 격리하는 것 — 이 셋이 "매일 도는 자동화"의 최소 골격이다.

10핵심 키워드 사전

11참고 링크

프로젝트
· 저장소: github.com/Thysrael/Horizon
· 라이브 데모(일일 브리핑): thysrael.github.io/Horizon
· 공식 사이트 · 출처 허브: horizon1123.top

저장소 안 문서
· 설정 전반: docs/configuration.md
· 프로파일 구조: docs/profiles.md · 점수 기준: docs/scoring.md
· 수집기별 설정: docs/scrapers.md · 본문 추출기: docs/extractors.md
· MCP 연동: src/mcp/README.md

이 문서에서 특히 볼 만한 소스 파일
· 파이프라인 전체 흐름: src/orchestrator.py의 run()
· 수집기 계약(47줄): src/scrapers/base.py
· 폴백 사다리 실물: src/scrapers/reddit.py · src/scrapers/telegram.py
· SSRF 방어: src/url_security.py
· 판단 기준(코드가 아닌 글): profiles/tech-news/analysis.md

배경 기술
· httpx: python-httpx.org · pydantic: docs.pydantic.dev
· uv: docs.astral.sh/uv · trafilatura: trafilatura.readthedocs.io
· MCP: modelcontextprotocol.io · GDELT DOC API: blog.gdeltproject.org