Horizon 딥다이브
— 흩어진 뉴스를 "나만의 AI 뉴스 레이더"로 모아 매일 브리핑하는 파이프라인의 설계

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Horizon은 한 줄로 말하면 "설정 가능한 개인용 AI 뉴스 어그리게이터"다. API 호출 한 번으로 끝나는 도구가 아니라, 7단계 워크플로(정의 → 수집 → 중복제거 → 점수·필터 → 보강 → 요약 → 배달)를 HorizonOrchestrator가 조율한다. AI 제공자는 Claude·GPT·Gemini·DeepSeek·Doubao·MiniMax·Ollama 등 OpenAI 호환 API를 자유롭게 꽂을 수 있고, 결과는 영어·중국어로 동시 생성된다. GitHub Actions 크론으로 매일 자동 실행해 Pages에 게시하는 것이 대표 사용 시나리오다.

2왜 주목받는가

트렌딩 이유 · 일반 RSS 리더/요약봇 대비 장점.

뉴스 요약봇은 흔하다. Horizon이 주목받는 이유는 "진짜 실전에서 골치 아픈 부분"을 파이프라인 단계마다 풀었기 때문이다. 첫째 7개 이질적 출처를 단일 모델(ContentItem)로 통합, 둘째 교차 출처 URL 병합 + AI 의미론적 중복 제거(같은 사건의 여러 보도 합치기), 셋째 0~10 점수화 후 임계값 필터로 노이즈 차단, 넷째 웹 검색으로 배경지식을 보강하고 댓글까지 요약, 다섯째 4가지 배달 채널 + MCP 노출이다.

3기술 스택 전체 지도

백엔드(파이프라인 엔진)·프론트엔드(브리핑/배달)·인프라 각각.

① 핵심 엔진 (백엔드) — 비동기 수집 + 멀티 LLM

Horizon은 100% 파이썬(3.11+)이며, 수집은 본질적으로 I/O 바운드(여러 사이트 응답 대기)라 httpx.AsyncClient + asyncio.gather로 모든 출처를 동시에 긁는다. AI 단계는 제공자 추상화 계층(ai/client.py)으로 어떤 LLM이든 같은 complete(system, user) 인터페이스로 부른다.

② 프론트엔드 · 출력 채널

③ 인프라 · 배포 · 자동화

4아키텍처 심화 분석

설정 → 동시 수집 → 병합 → 점수·필터 → 보강 → 이중언어 요약 → 배달.

전체 흐름 한눈에

입력은 JSON 설정 1개 + 시간 윈도우(기본 24시간). HorizonOrchestrator.run()이 전 단계를 조율한다. 설정에 켜진 스크래퍼들이 asyncio.gather로 동시에 콘텐츠를 긁어 와 모두 ContentItem으로 정규화하고, URL 병합 → AI 점수 → 임계값 필터 → AI 토픽 중복제거 → 카테고리 쿼터 → 웹검색 보강 → 언어별 요약 → 배달 순으로 흐른다. 각 단계가 명확한 "입력 리스트 → 출력 리스트" 변환이라 추적과 디버깅이 쉽다.

핵심 #1 — 통합 데이터 모델 ContentItem

아키텍처의 토대는 "7개 이질적 출처를 단 하나의 모델로 통일"한 것이다. HN 스토리든 트윗이든 GitHub 릴리스든, 스크래퍼는 전부 같은 ContentItem(pydantic 모델)을 반환한다. 이후 모든 단계는 출처가 무엇인지 신경 쓰지 않고 이 모델만 다룬다.

class ContentItem(BaseModel):
    id: str              # "{source}:{subtype}:{native_id}"
    source_type: SourceType   # github / hackernews / rss / reddit ...
    title: str
    url: HttpUrl
    content: Optional[str] = None
    author: Optional[str] = None
    published_at: datetime
    metadata: Dict[str, Any] = {}   # score, comments, subreddit ...
    # ── AI 분석 결과(나중에 채워짐) ──
    ai_score: Optional[float] = None   # 0~10 중요도
    ai_reason: Optional[str] = None
    ai_summary: Optional[str] = None
    ai_tags: List[str] = []

핵심 #2 — 두 종류의 중복제거

Horizon은 중복을 두 단계로 처리한다. 단순한 것은 코드로, 어려운 것은 AI로.

⑤가 영리한 점은 프롬프트(TOPIC_DEDUP_SYSTEM)에서 "같은 제품이라도 다른 사건이면 중복 아님"("Gemma 4 출시" vs "Gemma 4 탈옥")이라고 못 박고, 애매하면 분리 쪽으로 기우는(err on the side of keeping separate) 보수적 설계라는 점이다. 또 점수 내림차순으로 정렬된 상태에서 처리해 각 중복 그룹의 첫 번째(최고점)가 자동으로 대표가 되게 한다.

핵심 #3 — LLM 제공자 추상화

Horizon은 어떤 모델을 쓰든 코드가 바뀌지 않게 추상 기반 클래스 AIClient를 두고, complete(system, user) 하나로 통일했다. create_ai_client(config) 팩토리가 설정의 provider에 따라 Anthropic/OpenAI/Gemini 구현체를 만들어 준다. DeepSeek·Doubao·Ollama처럼 OpenAI 호환인 것들은 base_url만 바꿔 OpenAI 클라이언트를 재사용한다.

핵심 설계 패턴 정리

5디렉토리 구조 해부

src/ 안에 스크래퍼·AI·서비스·MCP가 책임별로 나뉘어 있다.

6학습 포인트 (기술별)

멀티소스 + AI 파이프라인에서 무엇을 배우나.

A. 파이프라인 아키텍처 — 큰 작업을 단계로 쪼개기

Horizon의 가장 큰 교훈은 "복잡한 일을 명확한 입출력을 가진 작은 단계의 사슬로 만들라"이다. run()을 읽으면 fetch→merge→score→filter→dedup→balance→enrich→summarize→deliver가 각각 "리스트를 받아 리스트를 반환"하는 변환임이 보인다. 이렇게 하면 단계마다 단위 테스트가 쉽고, 중간 결과를 로깅·검사할 수 있으며(실제로 MCP는 각 단계를 개별 도구로 노출), 새 단계 삽입도 쉽다.

B. 어댑터 패턴 — 이질적 출처를 하나의 모델로

7개 출처는 API·인증·응답 형식이 전부 다르다. Horizon은 이를 BaseScraper 추상 클래스 + 단일 ContentItem으로 흡수했다. 새 출처를 추가해도 fetch(since) -> List[ContentItem]만 구현하면 파이프라인 나머지는 손댈 필요가 없다. "외부 세계의 다양성을 경계에서 정규화하고, 내부는 단일 모델로 단순하게"의 모범이다.

C. LLM 제공자 추상화 — 모델 종속 끊기

ai/client.py는 "애플리케이션 코드가 특정 LLM SDK에 묶이지 않게 하는" 실전 예제다. 추상 AIClient.complete() 뒤로 Anthropic·OpenAI·Gemini 구현을 숨기고, OpenAI 호환 제공자는 base_url로 흡수한다. 이 덕분에 사용자는 설정 한 줄로 Claude ↔ GPT ↔ 로컬 Ollama를 갈아탈 수 있다. 벤더 락인을 피하는 설계를 배우기 좋다.

D. 견고한 비동기 수집 — 실패 격리와 동시성 제한

한 출처가 죽어도 전체가 멈추면 안 된다. Horizon은 gather(..., return_exceptions=True)로 예외를 결과로 받아 출처별로 격리하고, AI 단계는 Semaphore로 동시 호출 수를 제한해 레이트리밋·풀 고갈을 막는다. 또 tenacity로 지수 백오프 재시도를 건다. "외부에 의존하는 시스템은 반드시 실패를 전제로 설계하라"는 원칙의 실물.

E. 프롬프트 엔지니어링 — 점수화·중복판정을 데이터로 만들기

prompts.py는 "AI에게 시킬 판단을 어떻게 명세하나"의 교과서다. 점수 프롬프트는 9-10/7-8/5-6/3-4/0-2 각 구간을 구체 예시와 함께 정의하고, JSON으로만 응답하게 강제한다. 중복 프롬프트는 경계 사례("같은 제품 다른 사건")를 명시해 오판을 줄인다. 출력 포맷을 JSON으로 고정 + 파싱 실패 시 폴백(parse_json_response)하는 견고함도 배울 점이다.

7시스템 / 환경 요구사항

설치는 가볍지만 "API 키와 설정"이 실질적 진입 장벽이다.

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

난이도별 5단계 — 소스를 읽고 직접 손대 본다.

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

6주 코스 — 비동기 수집 기초부터 LLM 파이프라인 설계까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: Thysrael/Horizon
• 라이브 데모(일일 브리핑): thysrael.github.io/Horizon
• 설정 가이드: docs/configuration.md · 점수 기준: docs/scoring.md
• MCP 도구 레퍼런스: src/mcp/README.md
• 출처 공유 허브: horizon1123.top
• 관련 기술: httpx · pydantic · uv · Model Context Protocol