README.md

---
license: apache-2.0
base_model:
- amazon/chronos-2
- EleutherAI/polyglot-ko-1.3b
library_name: transformers
pipeline_tag: time-series-forecasting
language:
- ko
tags:
- jnu-tsb
- time-series
- forecasting
- chronos-2
- polyglot-ko
- korean
- finance
- covariates
- r
- reticulate
- education
---

# JNU-TSB

**JNU-TSB**는 한국어 뉴스와 주가 시계열을 함께 다루기 위한 교육용 **Time-LLM-style time-series bridge/router**입니다.

```text
Repo ID: HONGRIZON/JNU-TSB
Full name: Jeju National University Time-Series Bridge
Nickname: TSB = Time-Series Bridge, also Time-Series Seungbin
Time-series model: amazon/chronos-2
Korean language model: EleutherAI/polyglot-ko-1.3b
Router: stock only, news only, news + stock hybrid
```

이 저장소는 **Chronos-2 또는 Polyglot-Ko의 가중치를 재배포하지 않습니다.** 여기에는 가벼운 wrapper 코드, 설정 파일, 예제 코드, 샘플 데이터만 포함되어 있습니다. 두 base model은 실행 시 Hugging Face에서 다운로드됩니다.

## 개요

JNU-TSB는 한국어 금융 뉴스 제목을 일별 공변량으로 변환하고, 이를 Chronos-2에 전달해 공변량 기반 시계열 예측을 수행하는 wrapper-style model repo입니다.

```text
뉴스 제목
  -> Polyglot-Ko / keyword fallback
  -> 일별 14차원 이벤트 공변량
  -> Chronos-2 covariate-informed forecasting

주가 시계열
  -> Chronos-2 forecasting
```

이 구조는 **Time-LLM-style**입니다. 원 논문의 Time-LLM reprogramming architecture를 엄밀히 재구현한 것은 아닙니다. 숫자 시계열 예측은 Chronos-2가 담당하고, 한국어 LLM은 뉴스 텍스트를 구조화된 공변량으로 바꾸는 역할을 맡습니다.

## 라우터 구조

JNU-TSB는 입력에 따라 세 가지 경로 중 하나를 자동 선택합니다.

| 입력 | 경로 | 출력 |
|---|---|---|
| `stock`만 있음 | Chronos-2 단독 경로 | 분위수 시계열 예측 |
| `news`만 있음 | Polyglot-Ko / keyword fallback 경로 | 이벤트 카테고리, 감성, confidence, 일별 공변량 |
| `stock` + `news` 모두 있음 | 하이브리드 경로 | 뉴스 공변량을 포함한 Chronos-2 예측 |

하이브리드 경로는 다음 순서로 동작합니다.

```text
한국어 뉴스
  -> 이벤트/감성 추출
  -> 일별 14차원 covariate 생성
  -> 주가 context dataframe과 merge
  -> Chronos-2 predict_df 호출
  -> forecast 반환
```

## 14차원 뉴스 공변량

뉴스는 하루 단위로 집계되어 아래 14개 공변량으로 변환됩니다.

| 컬럼 | 의미 |
|---|---|
| `cov_earnings_count` | 실적/매출/영업이익 관련 뉴스 수 |
| `cov_product_count` | 제품 출시, 개발, 양산, 반도체 관련 뉴스 수 |
| `cov_macro_count` | 금리, 환율, 경기, 해외시장 등 거시경제 뉴스 수 |
| `cov_regulation_count` | 규제, 소송, 제재, 정부 정책 관련 뉴스 수 |
| `cov_supply_chain_count` | 공급망, 수주, 계약, 생산, 물류 관련 뉴스 수 |
| `cov_competition_count` | 경쟁사, 점유율, 가격 경쟁 관련 뉴스 수 |
| `cov_other_count` | 위 범주에 명확히 속하지 않는 뉴스 수 |
| `cov_sentiment_pos_count` | 긍정 감성 뉴스 수 |
| `cov_sentiment_neg_count` | 부정 감성 뉴스 수 |
| `cov_sentiment_neu_count` | 중립 감성 뉴스 수 |
| `cov_news_count` | 해당 날짜의 전체 뉴스 수 |
| `cov_sentiment_mean` | 평균 감성 점수, `-1`, `0`, `1` 기반 |
| `cov_confidence_mean` | 평균 추출 confidence |
| `cov_event_score` | 감성 × confidence의 합 |

## 설치

```bash
pip install -U transformers torch accelerate pandas pyarrow chronos-forecasting
```

R에서 사용할 경우 `reticulate` 가상환경에 위 Python 패키지를 설치하면 됩니다.

## Python 빠른 시작

빠른 테스트에서는 `use_llm_extractor=False`를 사용할 수 있습니다. 이 경우 Polyglot-Ko를 로드하지 않고 keyword fallback만 사용하므로 가볍게 실행됩니다.

```python
from transformers import pipeline

pipe = pipeline(
    task="jnu-tsb",
    model="HONGRIZON/JNU-TSB",
    trust_remote_code=True,
    device=-1,  # CPU. GPU 0번을 쓰려면 0으로 변경
)

stock = [
    {"timestamp": "2024-12-01", "target": 71000},
    {"timestamp": "2024-12-02", "target": 71800},
    {"timestamp": "2024-12-03", "target": 70400},
    {"timestamp": "2024-12-04", "target": 70900},
    {"timestamp": "2024-12-05", "target": 72100},
]

news = [
    {"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"},
    {"date": "2024-12-02", "title": "반도체 업황 둔화 우려"},
]

result = pipe(
    {"stock": stock, "news": news},
    prediction_length=3,
    use_llm_extractor=False,
)

print(result)
```

## AutoModel 직접 사용

```python
from transformers import AutoModel

model = AutoModel.from_pretrained(
    "HONGRIZON/JNU-TSB",
    trust_remote_code=True,
)

result = model.predict(
    stock=[{"timestamp": "2024-12-01", "target": 71000}],
    news=[{"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"}],
    prediction_length=3,
    use_llm_extractor=False,
)

print(result)
```

## R 빠른 시작

```r
library(reticulate)

# 최초 1회만 실행:
# reticulate::virtualenv_create("jnu-tsb-env")
# reticulate::virtualenv_install(
#   "jnu-tsb-env",
#   c("transformers", "torch", "accelerate", "pandas", "pyarrow", "chronos-forecasting")
# )

use_virtualenv("jnu-tsb-env", required = TRUE)
transformers <- import("transformers")

pipe <- transformers$pipeline(
  task = "jnu-tsb",
  model = "HONGRIZON/JNU-TSB",
  trust_remote_code = TRUE,
  device = -1L
)

stock <- list(
  list(timestamp = "2024-12-01", target = 71000),
  list(timestamp = "2024-12-02", target = 71800),
  list(timestamp = "2024-12-03", target = 70400)
)

news <- list(
  list(date = "2024-12-01", title = "삼성전자 HBM 신제품 출시"),
  list(date = "2024-12-02", title = "반도체 업황 둔화 우려")
)

result <- pipe(
  list(stock = stock, news = news),
  prediction_length = 3L,
  use_llm_extractor = FALSE
)

print(py_to_r(result))
```

## 입력 형식

### `stock`

`stock`은 pandas DataFrame, list of dicts, 또는 dict of columns 형식으로 넣을 수 있습니다. 최소 컬럼은 다음 두 개입니다.

```text
timestamp: 날짜 또는 시간
target: 예측 대상 값, 예: 종가
```

`item_id`가 없으면 내부적으로 `series_0`이 자동 부여됩니다.

### `news`

`news`는 list of dicts 형식입니다. 각 항목은 최소한 날짜와 제목을 가져야 합니다.

```json
[
  {"date": "2024-12-01", "title": "삼성전자 HBM 신제품 출시"},
  {"date": "2024-12-02", "title": "반도체 업황 둔화 우려"}
]
```

`title` 대신 `headline`, `text`, `content`도 인식합니다.

### `future_news`와 `future_covariates`

미래에 이미 알려진 뉴스나 일정이 있을 때만 `future_news` 또는 `future_covariates`를 사용하세요. 일반 뉴스 데이터는 보통 미래 값을 알 수 없으므로, 과거 뉴스는 context 구간의 past covariate로만 쓰는 것이 안전합니다.

## 출력 예시

출력은 사용된 route와 예측 결과를 함께 반환합니다.

```text
route: text_only | chronos_only | hybrid
repo_id: HONGRIZON/JNU-TSB
forecast: 예측 결과 또는 이벤트/공변량 결과
used_naive_fallback: Chronos-2 실행 실패 시 fallback 사용 여부
```

## 중요한 주의사항

- 이 모델은 교육/연구 데모용입니다. 투자 조언이나 실제 매매 판단에 사용하지 마세요.
- `EleutherAI/polyglot-ko-1.3b`는 instruction-tuned JSON extractor가 아니라 base language model입니다. 따라서 JSON 추출이 실패할 수 있고, 이 저장소는 keyword fallback을 함께 제공합니다.
- Chronos-2 또는 Polyglot-Ko 가중치를 이 저장소에 포함하지 않습니다. 실행 시 각 upstream repo에서 다운로드합니다.
- 이 저장소는 원 논문 Time-LLM을 그대로 재구현한 것이 아니라, 한국어 뉴스와 시계열 예측을 연결하는 Time-LLM-style wrapper/router입니다.

## 라이선스

Wrapper 코드는 Apache-2.0으로 배포됩니다. Upstream base model인 `amazon/chronos-2`와 `EleutherAI/polyglot-ko-1.3b`는 각 Hugging Face repo의 라이선스와 사용 조건을 따릅니다.