Metadata-Version: 2.4
Name: analyser2-hj3415
Version: 2.4.2
Summary: Analyse NFS data stored by db2/scraper2
Keywords: example,demo
Author-email: Hyungjin Kim <hj3415@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: yfinance>=1.2.0
Requires-Dist: lightgbm>=4.6.0
Requires-Dist: scikit-learn
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: db2-hj3415
Requires-Dist: logging-hj3415
Requires-Dist: contracts-hj3415
Requires-Dist: common-hj3415

# 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. 프로젝트 구조 설명

```text
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 사용법 (예시 포함)

설치:

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

도움말:

```bash
analyser2 --help
analyser2 features --help
analyser2 red --help
analyser2 prediction --help
```

자주 쓰는 실행 예시:

```bash
# 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 대신 코드에서 직접 유즈케이스를 호출할 수도 있습니다.

```python
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 환경변수를 함께 읽습니다.

```env
# 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`):

```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` 예시 (모노레포 루트 기준):

```yaml
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:
```

실행:

```bash
docker compose up --build
```

단발성 명령 실행:

```bash
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
```

