로그북

Trackio logbook는 실험의 추론 과정, 명령어, 결과, 도표, 산출물(체크포인트, 데이터셋 등), 에이전트 트레이스를 기록하기 위한 공유 가능한 실험 노트입니다. logbook은 워크스페이스의 .trackio/logbook 디렉터리에 로컬로 저장되며, 로컬에서 미리 보기하거나 정적 Hugging Face Space로 게시할 수 있습니다.

코딩 에이전트에 권장: 코딩 에이전트(예: Codex, Claude Code, Pi, OpenCode)와 Logbooks를 사용하는 가장 쉬운 방법은 코딩 에이전트에 다음 지시를 주는 것입니다:

trackio skills add
trackio logbook open
trackio logbook attach trace <path to current trace>

Work in this workspace's Trackio logbook. Before running any experiment or
script, create or select the relevant page with `trackio logbook page "..."`. Run every experiment command with `trackio logbook run -- <command>` ratherthan invoking it directly, which will log the code and its outputs into the logbook. 

더 자세한 내용과 세밀한 제어를 원하신다면 계속 읽어보세요!

로그북으로 에이전트 세션 시작

logbook를 사용하는 가장 쉬운 방법은 에이전트가 변경 사항을 만들거나 실험을 실행하기 전에 생성하는 것입니다:

trackio logbook open --title "Learning-rate sweep"

이 명령은 로컬 로그북을 생성하고 미리보기를 엽니다. 로컬 로그북만 생성하거나 연결하려면 --no-serve를 사용하세요. 브라우저를 열지 않고 미리보기를 시작하려면 --no-browser를 사용하거나, 다른 포트를 선택하려면 --port를 전달하세요.

에이전트에 Trackio 스킬을 부여합니다

사용 중인 코딩 에이전트에 Trackio 스킬을 설치하세요. Codex의 경우:

trackio skills add --codex

이 명령은 프로젝트에 스킬을 설치하고 Codex에 연결합니다. 필요할 경우 설치 후 새 Codex 세션을 시작하여 스킬을 로드할 수 있도록 하세요. 다른 지원되는 에이전트를 사용하는 경우 --codex를 해당 플래그, 예를 들어 --claude, --cursor, --opencode, 또는 --pi로 교체하세요.

이 스킬은 에이전트가 실험 명령을 직접 호출하는 대신 trackio logbook run -- ...로 코드를 실행하도록 지시합니다. 이 래퍼는 정확한 명령, 감지된 스크립트 및 구성 파일, 출력, 종료 코드, 소요 시간, 지원되는 출력 산출물을 기록합니다. 예를 들어:

trackio logbook page "Baseline"
trackio logbook run -- python train.py --learning-rate 0.001

학습 스크립트는 여전히 trackio.init(), trackio.log(), trackio.finish()를 정상적으로 사용해야 합니다. 워크스페이스에 로그북이 있는 경우, trackio.init()은 활성 Trackio 프로젝트에 라이브 대시보드 셀을 추가할 수도 있습니다.

활성 세션 트레이스를 첨부합니다

세션의 초반부에 현재 코딩 에이전트 전사본을 첨부하세요:

trackio logbook attach trace /absolute/path/to/current-session.jsonl --title "Agent session"

에이전트 런타임은 자신의 트랜스크립트가 저장되는 위치를 결정합니다. 해당 런타임의 세션 디렉터리를 사용하여 활성 대화에 해당하는 JSON 또는 JSONL 파일을 찾은 후, 타임스탬프와 메타데이터가 세션과 일치하는 파일을 첨부하세요. 활성 JSONL 파일은 세션이 종료되기 전에 첨부할 수 있으며, Trackio는 로컬 미리보기가 열려 있는 동안 파일을 새로고침합니다. 파일을 첨부하면 Workspace 기준선이 설정되므로, 이후 지원되는 모델 및 데이터 파일을 해당 세션과 연관 지을 수 있습니다.

Trackio는 기본적으로 첨부된 trace에서 일반적인 시크릿을 제거합니다. trace에는 프롬프트, 도구 입력, 명령 출력, 경로 또는 개인 데이터가 여전히 포함될 수 있으므로 게시 전에 검토하세요. --no-scrub는 이미 정제된 소스에 대해서만 사용하세요.

작업이 진행됨에 따라 페이지를 생성합니다

이미 로그북이 포함된 워크스페이스를 열면 해당 로그북에 연결됩니다. 로그북은 페이지로 구성되며, 다음을 사용하여 페이지를 생성하거나 선택합니다:

trackio logbook page "Baseline"

실험 콘텐츠 추가

Markdown, 코드, 도형, 산출물 또는 Trackio 대시보드를 내장합니다:

trackio logbook cell markdown "Baseline accuracy: 82.4%" --page "Baseline"
trackio logbook cell code --page "Baseline" --code-text "print(metrics)" --language python
trackio logbook cell figure --page "Baseline" --image plots/baseline.png
trackio logbook cell artifact "my-project/model:v1" --page "Baseline" --type model
trackio logbook cell dashboard my-project --page "Baseline"

실험 명령을 실행하고 명령, 출력, 스크립트 및 출력 파일을 한 번에 캡처하려면:

trackio logbook run --page "Sweep" -- python train.py --learning-rate 0.001

출력된 모델 및 데이터 파일은 기본적으로 artifact 셀로 기록됩니다. 이 캡처를 비활성화하려면 --no-artifacts를 전달하세요.

로그북을 프로그래밍 방식으로 읽기

trackio logbook read는 에이전트 친화적인 컴팩트한 뷰를 생성합니다. 로컬 워크스페이스, 게시된 Space ID, 또는 로그북 URL을 읽을 수 있습니다:

trackio logbook read
trackio logbook read pages
trackio logbook read page "Baseline"
trackio logbook read --json

셀을 전체적으로 검사해야 하는 경우 trackio logbook read cell <cell-id> --full을 사용하세요. JSON 형식은 자동화 및 코딩 에이전트에 유용합니다.

로그북 게시

현재 로그북을 Hugging Face Space에 게시합니다:

trackio logbook publish username/learning-rate-logbook

게시된 로그북은 정적이며 읽기 전용입니다. Space는 기본적으로 trace 데이터셋 및 아티팩트 버킷에 대한 참조를 저장합니다. 참조된 리소스도 공개해야 하는 경우에만 --public을 사용하세요. Space를 비공개로 만들려면 --private을 사용하세요.