Metadata-Version: 2.4
Name: labdash
Version: 0.2.0
Summary: Zero-dependency live dashboard for training logs. A tiny, local wandb.
License: MIT
Keywords: training,logs,dashboard,visualization,deep-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# labdash

학습 로그를 실시간으로 보여주는 작고 가벼운 로컬 대시보드입니다. "계정 없이, 코드 한 줄로 쓰는 wandb"를 목표로 합니다.
파이썬 표준 라이브러리만 사용하고, UI는 오프라인에서도 열리는 HTML 파일 하나입니다.

```bash
pip install labdash
```

## 가장 빠른 사용법: 설정도, 코드 수정도 필요 없습니다

기존 학습 명령 앞에 `labdash run`만 붙이면 됩니다.

```bash
labdash run python train.py --lr 1e-4      # .py 파일만 줘도 됩니다: labdash run train.py
```

브라우저에서 대시보드가 자동으로 열리고, 출력되는 `{'loss': ...}` 같은 줄을 읽어 실시간 차트로 보여줍니다.
출력은 터미널에 그대로 나오고, 기록은 `./labdash`에 저장됩니다. 학습이 끝난 뒤에도 `labdash`로 다시 볼 수 있습니다.
(포트는 사용 중이면 자동으로 다음 번호를 씁니다.)

## 사용법 (wandb 방식)

```python
import labdash
labdash.init(project="qwen-lora", name="r32-v1", config={"lr": 2e-4})   # 대시보드가 같이 열립니다
for step in range(1000):
    labdash.log({"loss": loss, "lr": lr, "eval": {"acc": acc}})          # 중첩 dict는 eval/acc 로 펴집니다
labdash.finish()                                                         # 생략 가능 (종료 시 자동 실행)
```

모든 run은 `./labdash/<project>/<run-id>/`에 저장됩니다. `metrics.jsonl`과 `meta.json`(config, 상태, 호스트, git 커밋)이 들어 있어서,
학습이 중간에 죽어도 기록이 남습니다. 프로세스가 끝난 뒤에도 언제든 다시 볼 수 있습니다.

```bash
labdash                  # ./labdash 안의 모든 run 표시 (run 메뉴에서 선택)
```

**이미 raw 로그를 출력하는 trainer가 있다면? 코드 수정 없이 수집할 수 있습니다.**

```python
labdash.init(capture_stdout=True)   # 지표처럼 보이는 줄(HF dict, JSON, key=value)을 자동 수집합니다. 출력은 그대로 나옵니다.
```

스크립트를 건드리지 않고 쓰려면 `python train.py 2>&1 | labdash -`(파이프)나, 기존 로그 파일을 따라 읽는 `labdash train.log`를 쓰면 됩니다.

환경 변수:
- `LABDASH_DIR`: 저장 위치
- `LABDASH_MODE=offline`: 파일만 저장하고 서버는 띄우지 않음
- `LABDASH_MODE=disabled`: 아무 동작도 하지 않음

torchrun/DDP 환경에서는 rank 0만 기록합니다. run 상태는 running / finished / crashed로 표시됩니다.

## 어디서나 동작

| 환경 | 방법 |
|---|---|
| 로컬 / SSH 서버 | `labdash train.log` 실행 후 `ssh -L 6006:localhost:6006 host` 터널, 또는 `--host 0.0.0.0` |
| Jupyter / Colab / VS Code 노트북 | `labdash.serve("train.log")`가 셀 안에 바로 표시됩니다 (셀을 막지 않음) |
| 서버를 못 여는 환경 (Modal, CI 등) | `labdash train.log --export report.html`로 HTML 파일 하나를 만들어 어디서든 열 수 있습니다 |
| HF Trainer / TRL / Unsloth | `Trainer(..., callbacks=[labdash.hf_callback()])` |
| Keras | `model.fit(..., callbacks=[labdash.keras_callback()])` |
| 그 외 | `labdash.log({...})`, `capture_stdout=True`, stdout 파이프, 로그 파일 tail |

Python 3.8 이상, Linux/macOS/Windows, 의존성 없음. 모든 URL이 상대 경로라서 리버스 프록시 뒤에서도 동작합니다.

## 인식하는 로그 형식

기본으로 다음을 인식합니다. 타임스탬프 같은 접두사가 붙어 있어도 됩니다.
- 파이썬 dict 또는 JSON 객체가 들어 있는 줄 (HF Trainer, Unsloth, TRL, Lightning 등)
- `key=value` 형태의 쌍

그 외의 줄(경고, tqdm 진행바 등)은 무시합니다. `'0.2316'` 같은 문자열 숫자도 처리합니다.
`step`/`global_step`과 `epoch`는 x축으로 쓰입니다.

`eval_<이름>_loss` 형태의 키는 한 차트에 겹쳐 그립니다 (예: `eval_loss` 차트에 answer와 trace).

다른 형식은 파서를 직접 등록하면 됩니다.

```python
@labdash.register_parser
def mine(line):
    if line.startswith("METRIC "):
        return dict(kv.split("=") for kv in line[7:].split())
```

## UI

- **run 비교:** run 메뉴에서 여러 run을 체크하면 같은 차트에 겹쳐 그립니다. run마다 색이 다르고,
  한 run 안의 추가 시리즈(`eval_*` 등)는 점선으로 구분합니다. 요약 카드에는 run별 최신/최소 loss가 나오고,
  config 패널에는 선택한 run들 사이에서 값이 다른 키만 표시됩니다.
- 자동 새로고침, x축 전환(step / epoch / index), EMA 스무딩, log-y, 차트 필터,
  차트 간 동기화되는 호버 툴팁, 라이트/다크 테마, 일시정지를 지원합니다.
