8-K 긴급 공시
실시간 모니터링

전체 구조: SEC RSS → HF Space → Supabase → 대시보드

파이프라인의 몸통은 HuggingFace Space다. Space 안에서 스케줄러가 10분마다 SEC EDGAR RSS를 확인하고, 새 8-K를 감지하면 파싱해서 Supabase에 저장한다. Gradio 대시보드는 그 데이터를 실시간으로 보여준다.

8-K란 무엇인가

8-K는 미국 상장사가 중요한 사건이 발생했을 때 4영업일 내에 제출해야 하는 긴급 공시다. 분기마다 나오는 정기 보고서(10-Q, 10-K)와 달리, 시장을 움직일 만한 일이 생기면 즉시 나온다.

NVIDIA 기준으로 실적 발표, 임원 변경, 대규모 계약, 주식 환매 같은 사건이 8-K로 공시된다. 그래서 8-K를 실시간으로 감지하는 것은 투자 정보 시스템의 기본기다 — 07_secrag에서 만든 RAG 도구가 과거 공시를 "검색"했다면, 이번 시스템은 새 공시를 "감시"한다.

계정 두 개, 패키지 설치, 테이블 하나

준비물은 세 가지다. HuggingFace 계정(Space 배포용), Supabase 계정(DB용, 무료 플랜으로 충분), 그리고 로컬 개발용 패키지.

pip install gradio apscheduler supabase requests beautifulsoup4 -q

Supabase 테이블 생성

Supabase 프로젝트를 만든 뒤 SQL Editor에서 아래를 실행해 filings 테이블을 만든다.

create table filings (
  id           bigserial primary key,
  ticker       text default 'NVDA',
  filing_type  text,
  filed_at     date,
  title        text,
  content      text,
  sec_url      text unique,
  analysis     text,
  created_at   timestamptz default now()
);

sec_url에 걸린 unique 제약이 이 시스템의 중복 방지 장치다. 같은 공시를 다시 저장하려 하면 DB가 거부하므로, 폴링을 아무리 반복해도 데이터가 두 번 쌓이지 않는다.

확인할 값

• Project URL — 설정 → API에서 확인
• anon key — 설정 → API에서 확인

이 두 값은 Step 1의 코드와 Step 3의 Space Secrets에서 사용한다.

check_and_store() — 감지에서 저장까지 한 함수로

SEC EDGAR는 회사별 공시를 RSS(atom) 피드로 공개한다. 새 공시가 나오면 피드에 항목이 추가되므로, 주기적으로 확인해서 새 항목만 Supabase에 저장하면 된다. 중복은 sec_url unique 제약이 자동으로 막아 준다.

NVIDIA 8-K 전용 RSS 주소는 다음과 같다 (CIK 0001045810이 NVIDIA다).

https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0001045810&type=8-K&dateb=&owner=include&count=10&output=atom

SEC EDGAR RSS 피드로 NVIDIA 8-K 공시를 감지해 Supabase에 저장하는 모듈을 만들어줘.
- RSS URL: (위 atom URL)
- requests + xml.etree.ElementTree로 RSS 파싱 (beautifulsoup4 금지)
- 각 항목에서 추출: title, filed_at, sec_url, 본문 텍스트(링크 따라가서 파싱)
- Supabase 저장: SUPABASE_URL/KEY, 테이블 filings, sec_url 중복 시 skip (upsert)
- 함수 check_and_store() 하나로 캡슐화
- 실행 시 "신규 X건 저장, Y건 중복 스킵" 출력
파일명: monitor_core.py

확인 포인트

• monitor_core.py를 실행하면 "신규 X건 저장, Y건 중복 스킵"이 출력된다
• Supabase Table Editor → filings 테이블에 행이 쌓여 있다
• 한 번 더 실행하면 전부 "중복 스킵"으로 처리된다 (unique 제약 동작 확인)

앱이 떠 있는 동안, 10분마다 스스로 돈다

APScheduler의 BackgroundScheduler는 Gradio 앱이 실행 중인 동안 별도 스레드에서 지정한 주기로 함수를 호출한다. 앱을 띄워 두기만 하면 check_and_store()가 10분마다 자동으로 실행되는 구조다.

monitor_core.py를 import해서 Gradio 모니터링 대시보드를 만들어줘.
- APScheduler BackgroundScheduler로 10분마다 check_and_store() 실행
- UI: 상단 "마지막 체크: [시각]" + [지금 체크] 버튼 / 중간 filings 최근 20건 gr.Dataframe(날짜, 제목, 공시유형, URL) / 하단 행 선택 시 본문 gr.Textbox
- [지금 체크] 클릭 시 즉시 실행 후 테이블 갱신, 앱 시작 시 스케줄러 자동 시작
- SUPABASE_URL, SUPABASE_KEY는 환경변수(os.environ)에서 로드
파일명: app.py

확인 포인트

• 앱 시작과 동시에 스케줄러가 자동으로 시작된다
• [지금 체크] 버튼을 누르면 즉시 실행되고 테이블이 갱신된다
• 최근 20건이 Dataframe에 표시되고, 행을 선택하면 본문이 보인다

무료로 24시간 호스팅되는 Gradio 앱

HuggingFace Spaces는 Gradio 앱을 무료로 24시간 호스팅한다. 로컬 PC를 꺼도 Space 위의 앱과 스케줄러는 계속 실행된다. Supabase URL/Key는 코드가 아니라 Space Secrets에 등록해 노출을 막는다.

업로드할 파일 구성

my-8k-monitor/
├── app.py
├── monitor_core.py
└── requirements.txt   (gradio, apscheduler, supabase, requests, beautifulsoup4)

배포 절차

1. HuggingFace에서 New Space 생성 (SDK: Gradio)
2. Settings → Secrets에 SUPABASE_URL, SUPABASE_KEY 등록
3. Files 탭에 위 3개 파일 업로드
4. 자동 빌드가 끝나면 Space URL이 생성된다

확인 포인트

• Space URL로 접속하면 대시보드가 뜬다
• 로컬 PC를 꺼도 Supabase에 데이터가 계속 쌓이면 성공

감지 → 자동 LLM 분석 → analysis 컬럼 저장

새 8-K가 감지되면 HF Inference API로 즉시 분석을 돌리고, 결과를 filings 테이블의 analysis 컬럼에 저장한다. 대시보드는 분석 완료 여부를 표시하고, 행을 선택하면 원문과 AI 분석을 나란히 보여준다.

07_secrag에서 만든 SEC RAG 도구의 벡터 DB는 히스토리 검색용이고, 신규 8-K 분석은 여기서 별도 처리한다는 점을 구분해 두자.

요청 1 — monitor_core.py 수정

check_and_store()에 자동 RAG 분석 기능을 추가해줘.
- 새 8-K 저장 직후 HF Inference API(Qwen/Qwen3-8B, HF_TOKEN 환경변수) 분석
- 분석 프롬프트: "다음 NVIDIA 8-K 공시를 분석하시오. 1. 공시 핵심 내용 (2~3줄) 2. 투자자 관점에서 중요한 이유 3. 긍정/부정/중립 중 시장 영향 예상. 한국어로 답변. [공시 내용]: {content}"
- 결과를 analysis 컬럼에 업데이트, 실패 시 "분석 실패" 저장 후 계속 진행

요청 2 — app.py 수정

대시보드에 분석 결과 표시 기능을 추가해줘.
- Dataframe에 analysis 컬럼 (있으면 ✅, 없으면 ⏳)
- 행 선택 시 왼쪽 8-K 원문 / 오른쪽 AI 분석(gr.Markdown)
- 분석 없는 항목 선택 시 [지금 분석] 버튼 → 즉시 분석

확인 포인트

• 새 공시가 저장되면 analysis 컬럼에 분석 결과가 함께 채워진다
• 대시보드 Dataframe에 분석 완료 ✅ / 대기 ⏳ 표시가 보인다
• 행 선택 시 왼쪽 원문, 오른쪽 AI 분석이 나란히 표시된다
• 분석이 없는 항목은 [지금 분석] 버튼으로 즉시 분석된다

새 8-K 감지 → 텔레그램 즉시 발송

텔레그램 봇 API는 토큰과 chat_id만 있으면 HTTP POST 한 번으로 메시지를 보낼 수 있다. check_and_store()가 신규 공시를 저장한 직후 알림을 발송하게 연결한다.

발송할 메시지 구성: "📡 NVIDIA 새 8-K 공시 / 제목 / 날짜 / 분석(AI 요약 2~3줄) / 원문 URL"

봇 만들기 (1회)

@BotFather에서 /newbot → 봇 이름·계정명(…bot) 입력 → 토큰 발급 → 봇에게 /start를 보낸 뒤 https://api.telegram.org/bot[토큰]/getUpdates에서 message.chat.id를 확인한다. 그룹에 연결하려면 봇을 그룹에 초대한 뒤 같은 방법으로 확인하며, 그룹의 chat.id는 음수다. (막히면 아래 해설의 상세 가이드를 펼쳐서 따라 한다.)

monitor_core.py에 텔레그램 알림 기능을 추가해줘.
- 환경변수 TELEGRAM_TOKEN, TELEGRAM_CHAT_ID
- 함수 send_telegram(title, filed_at, analysis, sec_url)
- API: POST https://api.telegram.org/bot{token}/sendMessage (parse_mode: Markdown)
- 메시지: "📡 *NVIDIA 새 8-K 공시* / *제목:* / *날짜:* / *분석:* [앞 300자] / *원문:*"
- check_and_store()에서 신규 저장 후 호출, 발송 실패 시 print만 하고 계속, TOKEN 없으면 알림 없이 정상 동작

완성되면 Space의 Settings → Secrets에 TELEGRAM_TOKEN, TELEGRAM_CHAT_ID를 추가한다.

확인 포인트

• 로컬 실행 → 봇 채팅방에 메시지가 수신된다
• 신규 공시가 없어 테스트가 안 되면: Supabase에서 행 하나를 지우고 재실행 (신규로 재감지된다)
• Space Secrets에 TELEGRAM_TOKEN, TELEGRAM_CHAT_ID가 등록되어 있다

세 구성 요소의 역할

비용

확장 아이디어

• 다른 종목 모니터링 — ticker와 CIK만 바꾸면 어떤 미국 상장사든 같은 구조로 감시할 수 있다.
• Slack·이메일 알림 — 텔레그램 자리에 webhook을 추가하면 채널을 늘릴 수 있다.
• 감성 분석 차트 — 축적된 analysis의 긍정/부정/중립을 시계열 차트로 시각화한다.
• 벡터 DB 추가 인덱싱 — 신규 8-K를 07_secrag의 기존 벡터 DB에 추가해 히스토리 검색까지 통합한다.

출처 원본 노션 실습 자료: 8-K 긴급 공시 실시간 모니터링 (HuggingFace + Supabase)