analyser2-hj3415 2.4.2

Analyse NFS data stored by db2/scraper2

analyser2-hj3415 README

analyser2-hj3415는 DB에 저장된 NFS/Universe 데이터를 읽어 features, red, prediction 분석 결과를 생성하는 CLI 프로젝트입니다.

pyproject.toml 기준 정보:

• 패키지명: analyser2-hj3415
• 버전: 2.4.1
• Python: >=3.11
• CLI 엔트리포인트: analyser2 = analyser2_hj3415.cli.app:app

1. 프로젝트 기능 설명

주요 기능은 아래 3가지입니다.

• features: NFS 데이터를 기준으로 feature 분석 결과 생성/저장
• red: 종목별 RED 분석 결과 생성/저장
• prediction: 모델 학습, 예측 결과 생성, 저장된 결과 조회

실무 기준으로는 “수집된 원천 데이터(NFS) -> 분석 결과(analysis/prediction)”를 자동화하는 분석 배치 CLI라고 보면 됩니다.

2. 프로젝트 구조 설명

analyser2-hj3415/
├─ pyproject.toml
└─ src/analyser2_hj3415/
   ├─ cli/
   │  ├─ app.py            # analyser2 루트 커맨드
   │  ├─ features.py       # analyser2 features ...
   │  ├─ red.py            # analyser2 red ...
   │  ├─ prediction.py     # analyser2 prediction ...
   │  ├─ tools.py          # 진단/점검 도구
   │  └─ test.py           # 스모크 테스트
   ├─ app/
   │  ├─ settings.py       # 환경변수 로딩
   │  ├─ composition.py    # 의존성 조립
   │  ├─ features/         # feature 도메인/유즈케이스
   │  ├─ red/              # red 도메인/유즈케이스
   │  ├─ prediction/       # 학습/예측/조회 유즈케이스
   │  ├─ infra/            # DB/입출력 어댑터
   │  └─ shared/           # 공통 리더/상수/타입
   └─ .env

처음 사용하는 경우는 cli만 실행하면 되고, 코드 통합이 필요할 때 app.composition과 각 usecases를 임포트하면 됩니다.

3. CLI 사용법 (예시 포함)

설치:

cd packages/analyser2-hj3415
python -m pip install -e .

도움말:

analyser2 --help
analyser2 features --help
analyser2 red --help
analyser2 prediction --help

자주 쓰는 실행 예시:

# 1) 스모크 테스트
analyser2 test all --universe krx300

# 2) features 단건/전체
analyser2 features one 005930 c103
analyser2 features all --universe krx300 --limit 20

# 3) red 단건/전체
analyser2 red one 005930
analyser2 red all --universe krx300

# 4) prediction 학습/예측/조회
analyser2 prediction train today --universe krx300
analyser2 prediction models --verbose false
analyser2 prediction predict forecast_krx300_2026-03-29 today --universe krx300
analyser2 prediction results forecast_krx300_2026-03-29 today --limit 20
analyser2 prediction latest 005930 --universe krx300

4. 다른 프로젝트에서 임포트해서 사용하는 예시

CLI 대신 코드에서 직접 유즈케이스를 호출할 수도 있습니다.

import asyncio

from analyser2_hj3415.app.composition import build_components
from analyser2_hj3415.app.shared.constants import FeaturesEPEnum


async def main() -> None:
    components = build_components()
    try:
        # features: 단건 실행 예시
        summary = await components.features.run_batch.run(
            codes=["005930"],
            endpoints=[FeaturesEPEnum.C103],
            fail_fast=False,
        )
        print(summary.total, summary.ok, summary.failed)
    finally:
        await components.resources.aclose()


asyncio.run(main())

5. 환경변수 설정 예시

기본적으로 src/analyser2_hj3415/.env와 OS 환경변수를 함께 읽습니다.

# app
APP_NAME=analyser2
APP_ENV=prod
LOG_LEVEL=INFO

# db
MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=hj3415
MONGO_CONNECT_TIMEOUT_MS=5000
MONGO_SERVER_SELECTION_TIMEOUT_MS=5000
SNAPSHOT_TTL_DAYS=730

# analyser
ANALYSER2_SINK=mongo
FEATURE_LAST_N=4
FEATURE_DEFAULT_PREFER=chosen
RED_EXPECT_EARN=0.06
RED_SIGMOID_K=1.5
PREDICTION_MODEL_DIR=.artifacts/prediction_models
PREDICTION_TICKER_SUFFIX=.KS

운영 포인트:

• ANALYSER2_SINK는 mongo | stdout | both 중 선택
• PREDICTION_MODEL_DIR는 모델 파일 저장 경로이므로 운영에서는 영속 스토리지 권장
• prediction 기능은 yfinance를 사용하므로 네트워크가 필요

6. Dockerfile + docker-compose.yml 사용 예시

이 프로젝트는 CLI 단독 실행이 가능하므로 컨테이너 기반 실행 예시를 제공합니다.

Dockerfile 예시 (packages/analyser2-hj3415/Dockerfile):

FROM python:3.11-slim

WORKDIR /app
COPY . /app

RUN python -m pip install --upgrade pip && \
    python -m pip install .

ENTRYPOINT ["analyser2"]

docker-compose.yml 예시 (모노레포 루트 기준):

version: "3.9"

services:
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db

  analyser2:
    build:
      context: ./packages/analyser2-hj3415
      dockerfile: Dockerfile
    environment:
      APP_NAME: analyser2
      APP_ENV: prod
      LOG_LEVEL: INFO
      MONGO_URI: mongodb://mongo:27017
      MONGO_DB_NAME: hj3415
      ANALYSER2_SINK: mongo
      FEATURE_LAST_N: "4"
      FEATURE_DEFAULT_PREFER: chosen
      RED_EXPECT_EARN: "0.06"
      RED_SIGMOID_K: "1.5"
      PREDICTION_MODEL_DIR: /models
      PREDICTION_TICKER_SUFFIX: .KS
    volumes:
      - analyser2_models:/models
    depends_on:
      - mongo
    command: ["test", "all", "--universe", "krx300"]

volumes:
  mongo_data:
  analyser2_models:

실행:

docker compose up --build

단발성 명령 실행:

docker compose run --rm analyser2 features one 005930 c103
docker compose run --rm analyser2 red one 005930
docker compose run --rm analyser2 prediction train today --universe krx300