Metadata-Version: 2.4
Name: pueue-pmon
Version: 0.1.0
Summary: Read-only live terminal monitor for pueue queues
License-Expression: MIT
Keywords: pueue,monitor,terminal,queue
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: third_party/pueue/LICENSE.MIT
License-File: third_party/pueue/LICENSE.APACHE
Dynamic: license-file

# pmon

pueue queue의 **읽기 전용 실시간 모니터 / Python 패키지**입니다.
실험 코드를 수정하지 않고 실행·대기·완료·실패 상태, 그룹, 경과 시간,
의존성과 작업 로그를 봅니다. 실험 내부 진행률은 추정하지 않으며
DiD의 진행 파일이나 실행 코드는 읽거나 수정하지 않습니다.

## 설치

PyPI 배포명은 **pueue-pmon**, 실행 명령은 **pmon**입니다.
아래 명령은 PyPI 게시 후 사용할 수 있습니다. 현재는 로컬 배포 준비 단계입니다.

```bash
pip install pueue-pmon
pmon --config /path/to/project/.pueue/config.yml
```

설치 패키지는 OS에 맞는 공식 pueue·pueued 바이너리도 함께 설치합니다.
SHA-256과 버전을 고정하고 upstream MIT/Apache 라이선스를 동봉합니다.
Homebrew·Cargo·관리자 권한이 필요 없고 설치 후 추가 다운로드도 없습니다.
`pmon-pueue`, `pmon-pueued` 명령으로 포함된 도구를 사용할 수 있습니다.
기존 시스템의 pueue 명령을 덮어쓰지 않습니다.

```bash
pmon-pueue --version
pmon-pueue --config /workspace/project/.pueue/config.yml status
```

명시적인 도구 실행은 upstream 기능을 제공하지만, pmon 모니터는 읽기 전용입니다.
도구 실행 시 `--config` 또는 `PUEUE_CONFIG_PATH`가 필요합니다.
설정에는 상태·로그·소켓 경로도 workspace 안으로 지정하세요.

제공 대상: macOS ARM64/x86_64, Linux ARM64/x86_64, Windows x86_64.
macOS 최소 버전은 바이너리의 Mach-O 정보로 결정합니다.
Linux는 공유 라이브러리 의존성이 없는 ELF인지 빌드에서 검사합니다.
실제 실행 검증은 macOS ARM64에서 수행하며 다른 OS는 해당 OS에서 추가 검증이 필요합니다.

## 소스 실행

필요한 것: Python 3.11+, 이미 실행 중인 pueue daemon.
배포 wheel에는 공식 pueue·pueued 4.0.4가 포함되어 별도 설치가 필요 없습니다.
설치만으로 daemon이나 queue를 시작하지는 않습니다.
추가 Python 라이브러리나 전역 설치는 필요 없습니다.

```bash
cd /path/to/workspace/pmon
./pmon
```

개인 연결 설정은 `pmon.toml`에 저장하고 배포에는 포함하지 않습니다.
다른 daemon에는 다음처럼 연결합니다.

```bash
./pmon --config /path/to/project/.pueue/config.yml --group gpu
./pmon --log       # 실행 중인 첫 작업의 최근 로그
./pmon --log 2     # 작업 2의 최근 로그
./pmon --interval 5
./pmon --once      # 한 번 조회
./pmon --json      # 환경변수를 제외한 상태 JSON
```

기본 2초마다 갱신합니다. `q` 또는 `Ctrl+C`는 화면만 종료하며,
`r`은 즉시 갱신합니다. 연결 오류 시 마지막 성공 화면을 유지하고 재시도합니다.
로그는 최근 12줄만 조회하고 화면에는 최대 6줄 표시합니다. task 환경변수는
표시하지 않지만 작업 로그 자체는 해당 작업이 출력한 내용입니다.

소스 실행기는 설치된 Python 3.11+를 찾습니다.
`PMON_PYTHON=/path/to/python ./pmon`으로 환경을 지정할 수도 있습니다.
외부 launcher, alias, shell 설정, 캐시나 로그를 만들지 않습니다.

## 연결 설정

`pmon.toml.example`을 참고합니다. 상대 경로는 설정 파일 기준입니다.

```toml
[connection]
config = "../another-project/.pueue/config.yml"
group = "gpu"  # 생략 시 전체 그룹
```

`--settings /path/to/pmon.toml`로 다른 설정을 선택합니다.
명시적인 `--config`가 우선합니다. 패키지 CLI에 설정이 없으면 현재 폴더의
`.pueue/config.yml`만 확인하며, 홈 폴더 기본 설정을 만들지는 않습니다.
daemon 자체의 상태·로그 저장 위치는 연결 대상 pueue 설정을 따릅니다.

## Python API

```python
from pmon import Client

client = Client("/path/to/project/.pueue/config.yml")
for task in client.status(group="gpu").tasks:
    print(task.id, task.status, task.label)
print(client.log(2, lines=10))
```

패키지는 `src/pmon`에 있고, `pyproject.toml`에 설치용 metadata와 `pmon`
CLI 진입점을 정의했습니다. PyPI에 배포한 상태는 아닙니다.
이 checkout은 설치 없이 `./pmon`으로 사용할 수 있습니다.

## 검사

모든 변경과 임시 파일은 이 디렉터리 안에 둡니다.

```bash
mkdir -p .tmp
PYTHONPATH=src python3.13 -B -m unittest discover -s tests -v
```

pueue 4.0.4의 실제 daemon에 읽기 전용 연결을 검증했습니다.

## 배포 준비

[RELEASING.md](RELEASING.md)에 빌드·설치 검증·업로드 절차를 기록합니다.
모든 환경과 캐시, 빌드 출력은 이 폴더 안에 둡니다.
