Project Bourne

Project Bourne은 재현 가능한 과학·공학 워크로드를 위한 오픈소스 실행 및 출처(provenance) 인프라입니다.

로컬 머신, GPU, Slurm, PBS에서 계산 실험을 계획하고 실행하며, 입력·출력·실행 컨텍스트·아티팩트 계보(lineage)·원격 측정(telemetry)·검증·결과 재현에 필요한 이력을 보존합니다.

연구자, 학부생부터 박사과정까지의 학생, 교수진, 연구 엔지니어, 계산과학자, 과학 소프트웨어 사용자, 그리고 학계·공공 연구·산업 R&D의 과학 컴퓨팅 팀을 위해 설계되었습니다.

빠른 시작

인간(Human)

인간용 CLI는 현재 공개되어 있습니다:

python -m pip install bourneprov

bourne run python examples/demo.py
bourne list
bourne show @1

# Or execute an ExecutionRequest v1 document:
bourne execute --request bourne.json

에이전트 / MCP

v0.6.0 에이전트 및 MCP 진입점이 공개되어 있습니다:

python -m pip install "bourneprov[mcp]==0.6.0"
npx -y @project-bourne/mcp@0.6.0

소스 체크아웃에서 개발하는 경우 대신:

python -m pip install -e ".[mcp]"
bourne mcp

Related MCP server: heddle

Bourne을 사용하는 이유

Bourne은 과학 프로그램을 수정할 필요 없이 임의의 실행 파일을 감쌉니다. 로컬 우선(local-first)이며 프레임워크에 구애받지 않습니다: Python, 컴파일된 솔버, Julia, MPI 프로그램 및 기타 명령어가 동일한 지속적 실험 모델을 사용합니다.

bourne run bash -c "echo hello"
bourne run ./solver case.yaml
bourne run julia simulation.jl
bourne run mpirun -np 64 ./solver

프로그램의 stdout과 stderr는 실행 중에도 계속 표시되며 실험 기록에 보존됩니다.

아키텍처

Bourne Core는 결정적 실행, 계획, 저장, 출처를 담당합니다. 인간은 CLI 또는 Python 서비스를 통해 사용할 수 있고, 에이전트는 선택적 MCP 어댑터를 통해 동일한 서비스를 사용할 수 있습니다:

             Project Bourne Core
                    │
       ┌────────────┼────────────┐
       │            │            │
      CLI          SDK          MCP
    humans                     agents

에이전트 인터페이스는 선택적 접근 경로이지 Bourne의 제품 정체성이 아닙니다. MCP는 휴대용 Skill 없이도 작동하며, Bourne에는 내장 LLM이 포함되어 있지 않습니다.

에이전트 및 MCP 통합

표준 로컬 stdio 서버는 bourne mcp입니다. 공식 MCP Registry 식별자는 io.github.KozakHou/project-bourne이며, 휴대용 Agent Skill은 skills/project-bourne에 있습니다. v0.6.0 npm 패키지와 해당 Registry 항목이 공개되어 있습니다.

MCP 호환 에이전트는 "이 시뮬레이션을 GPU 4개로 실행하고 출처를 보존하라"와 같은 명시적 요청을 ExecutionRequest v1로 변환하고, Bourne에 계획을 요청하고, 결정적 해석을 보여주고, 실행 의도가 확립된 후 불변 계획을 실행할 수 있습니다. Bourne 자체는 제약 없는 자연어를 해석하지 않으며 다른 모델을 호출하지 않습니다.

에이전트 경로는 의도적으로 2단계로 구성됩니다:

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

계획 단계는 워크로드를 실행하거나 인프라를 조용히 발견하지 않습니다. 모호한 대상과 알 수 없는 사실은 미해결 상태로 남습니다. MCP 주석은 호스트 UX 힌트일 뿐입니다. Bourne Core는 여전히 불변 계획, 정확한 argv, 스케줄러 작업 소유권, 아티팩트 의미론, 출처를 강제합니다. MCP 통합 및 에이전트 가이드를 참조하세요.

실행 요청(Execution Requests)

이제 실행을 제한된 버전 관리 JSON 요청으로 한 번에 기술할 수 있습니다:

{
  "kind": "bourne.execution-request",
  "version": 1,
  "command": ["python", "train.py", "--case", "case1"],
  "artifacts": {
    "inputs": ["config.yaml"],
    "outputs": ["result.h5"]
  },
  "resources": {"cpus": 8, "gpus": 1, "walltime": "2h"},
  "execution": {"backend": "direct"},
  "verification": {
    "checks": [
      {"type": "output_exists", "path": "result.h5"},
      {"type": "output_min_bytes", "path": "result.h5", "min_bytes": 1024}
    ]
  }
}

bourne.json으로 저장한 후, 동일한 의도를 계획 또는 실행에 사용하세요:

bourne request validate bourne.json
bourne request show bourne.json

bourne discover
bourne plan --request bourne.json
bourne execute --request bourne.json

아무것도 실행하거나 발견하지 않고 최소 요청을 생성하려면:

bourne request init --output bourne.json -- python train.py
bourne request schema > execution-request-v1.schema.json

기존 플래그 기반 명령은 계속 지원됩니다. 이들은 병렬 구현이 아닌 동일한 ExecutionRequest → WorkloadSpec → ExecutionPlan 파이프라인으로 컴파일됩니다:

bourne execute --backend direct --cpus 2 --output result.txt -- python script.py

요청 파일의 경우, 상대 working_directory는 요청 파일이 있는 디렉터리 기준으로 해석됩니다. 선언된 아티팩트는 그 과학 작업 디렉터리에서 해석됩니다. Bourne은 어휘적 및 해석된 작업 디렉터리 값을 모두 보존하며, 파싱이나 계획 중에 $HOME을 확장하거나, 셸 구문을 평가하거나, 프로젝트 코드를 가져오거나, 아무것도 실행하지 않습니다.

상위(parent) 참조도 동일한 의도 보존 규칙을 따릅니다. 요청은 latest, @N, 고유 접두사 또는 전체 ULID를 사용할 수 있습니다. Bourne은 해당 요청 값을 유지하면서, 컴파일된 워크로드가 사용한 표준 상위 ULID를 별도로 기록합니다.

요약 원격 측정은 기본적으로 활성화되어 있으며 이미 캡처된 사실(벽시계 시간, UTF-8 stdout/stderr 바이트 수, 알려진 아티팩트 바이트 합계, 요청된 리소스, 관찰된 할당, 타임스탬프가 이를 확립하는 경우 스케줄러 대기열 타이밍)을 사용합니다. "telemetry": {"mode": "off"}는 요약을 비활성화합니다. 누락된 메트릭은 0이 아닌 "사용 불가"로 유지됩니다.

초기 결정적 검증 검사는 output_exists, output_min_bytes, output_sha256입니다. 이들은 캡처된 선언 출력 Artifact 레코드만 평가합니다. 검증은 프로세스 상태와 별도로 저장됩니다: 실험이 completed인 동안 검증은 failed 또는 unknown일 수 있습니다. 이러한 검사는 아티팩트 사실을 확립할 뿐 일반적인 과학적 타당성을 확립하지 않습니다. 정확한 계약 및 안전 한계는 실행 요청, 원격 측정 및 검증을 참조하세요.

계획 및 실행

Project Bourne v0.4.0은 v0.3 인벤토리 위에 지속적 계획 계층을 추가합니다:

bourne discover

bourne plan --backend direct -- python examples/demo.py
bourne execute --backend direct -- python examples/demo.py

bourne execution list
bourne execution show @1

bourne plan은 과학 명령을 실행하지 않으며 발견(discovery)을 수행하지 않습니다. 프레임워크 독립적인 WorkloadSpec을 생성하고, 명시적 및 추론된 요구 사항을 기존 인벤토리와 비교하고, 각 후보를 설명하고, 선택이 명확한 경우에만 불변 ExecutionPlan을 저장합니다. 필요 시 명시적 리소스 및 배치 제약 조건을 사용하세요:

bourne plan \
  --backend slurm \
  --target gpu \
  --cpus 16 \
  --gpus 4 \
  --nodes 1 \
  --memory 64G \
  --walltime 2h \
  -- ./solver case.yaml

선택한 Slurm 계획을 실행한 후 결과 실행 시도를 검사하거나 대기하세요:

bourne execute --plan @1
bourne execution show @1
bourne execution wait @1

기록된 작업이 아직 활성 상태인 동안 bourne execution cancel @1은 해당 Bourne 관리 작업의 취소를 요청합니다. 동일한 계획 및 수명 주기 모델이 --backend pbs를 지원합니다.

직접 실행은 Bourne의 기존 실시간 출력, 프로세스 그룹, 아티팩트, 계보, 실험 출처 메커니즘을 재사용합니다. Slurm 및 PBS 계획은 계획과 함께 스테이징된 자체 포함 Bourne 워커를 사용합니다. 워커는 사전 점검(preflight)을 수행하고 실제 할당된 호스트와 과학 실험을 기록합니다. 액세스 측 컨트롤러는 그 경계가 있는 JSON 결과를 트랜잭션 방식으로 가져옵니다. 계산 노드 SSH 또는 사전 설치된 bourneprov 패키지는 필요하지 않지만, 계산 할당은 Python 3와 스테이징 및 작업 디렉터리에 대한 가시성을 제공해야 합니다.

제출은 실험이 아니고, 스케줄러 완료는 과학적 성공이 아니며, 요청된 리소스는 할당된 리소스가 아닙니다. Bourne은 이를 별도의 지속적 사실로 기록합니다. 취소는 임의의 스케줄러 작업 ID가 아닌 Bourne 실행 참조를 허용하며 제출 신원을 확인합니다. 정확한 모델, 안전 경계 및 현재 제한 사항은 워크로드 계획 및 스케줄러 실행을 참조하세요.

컴퓨트 사이트 발견 (v0.3.0)

Bourne은 현재 신원에 보이는 실행 표면의 불변 로컬 스냅샷을 생성할 수 있습니다:

bourne discover
bourne inventory
bourne inventory --find python
bourne inventory --json

발견은 현재 신원 및 액세스 대상, 허용 목록에 포함된 사용자 관련 저장 경로, 직접 실행 컨텍스트, 일반 PATH 실행 파일, 선택적 Conda/virtualenv/컨테이너/모듈 컨텍스트, 안전한 시스템 기능, Bourne 기록, 그리고 가능한 경우 읽기 전용 Slurm/PBS 대상 클래스 요약을 포함합니다. 알 수 없는 실행 파일은 실행하지 않고 일반적으로 기록됩니다. 노트북, 데스크톱 및 GPU 워크스테이션, DGX급 개인 머신, 공유 연구실 시스템, 스케줄러 기반 HPC 사이트는 모두 유효한 컴퓨트 사이트입니다. 스케줄러가 없는 머신도 그 자체로 완전합니다.

발견은 관찰적입니다: 실행 파일이 워크로드 호환성으로 검증된 것이 아니고, 보이는 스케줄러 파티션이 제출 권한의 증거가 아니며, 저장 역할 힌트는 보존 또는 백업 정책이 아닙니다. 인벤토리는 로컬에 유지됩니다. 프로바이더는 다른 사용자의 홈 디렉터리를 탐색하지 않고, 공유 저장소를 크롤링하지 않으며, SSH 자격 증명이나 컨테이너 비밀을 검사하지 않고, 임의의 환경 변수를 덤프하지 않으며, 계산 노드에 SSH로 접속하지 않고, 스케줄러 작업을 제출하거나 취소하지 않으며, 환경을 수정하지 않습니다. 정확한 토폴로지, 증거, 한계 및 보안 의미론은 컴퓨트 사이트 발견을 참조하세요.

출처, 아티팩트 및 계보

Project Bourne v0.2는 명시적 입력/출력 지문, 최소한의 derived_from 관계, 안전한 실행 컨텍스트 관찰, 아티팩트 추적을 추가합니다. 격리된 디렉터리에서 결정적 예제를 실행하세요:

cp -R examples/provenance /tmp/bourne-provenance-demo
cd /tmp/bourne-provenance-demo
export BOURNE_DB="$PWD/bourne.sqlite3"

bourne run \
  --input config_A.json \
  --output result_A.csv \
  -- python demo_simulation.py config_A.json result_A.csv

bourne run \
  --derived-from @1 \
  --input config_B.json \
  --input result_A.csv \
  --output result_B.csv \
  -- python demo_simulation.py config_B.json result_B.csv

bourne show @2
bourne show @1
bourne trace result_B.csv

입력은 실행 전에 지문이 기록됩니다. 출력은 실행 후에 지문이 기록되며, 실패하거나 중단된 실행 후 누락된 예상 출력도 포함합니다. SHA-256 읽기는 청크 단위로 스트리밍됩니다. Bourne은 선언된 파일을 복사하거나 업로드하지 않습니다.

경로는 아티팩트 정체성이 아닙니다. 각 캡처는 안정적인 ULID를 가지며, SHA-256은 콘텐츠 버전을 구분합니다. 과거 경로가 여러 버전을 식별할 수 있고 현재 파일 콘텐츠가 이를 구분할 수 없을 때, bourne trace는 후보를 나열하고 추측을 거부합니다.

정확한 캡처, 추적, 마이그레이션 및 보안 의미론은 아티팩트, 계보 및 실행 컨텍스트를 참조하세요.

인간 친화적 실험 참조

표준 실험 식별자는 26자 ULID입니다. 실험을 허용하는 명령은 다음도 이해합니다:

01M02GDJEW...   case-insensitive unique ULID prefix
latest          most recent experiment
@1              most recent experiment
@2              second-most-recent experiment
@3              third-most-recent experiment

예를 들어:

bourne show latest
bourne show 01M02GDJEW
bourne compare @2 @1
bourne run --derived-from @1 -- ./solver case_B.yaml

Bourne은 접두사가 모호할 때 추측하지 않습니다. bourne list는 기본적으로 10자 접두사를 표시하며, bourne list --full-id는 표준 ID를 표시합니다.

셸 완성

완성 후보에는 표준 실험 ID, latest, 최근 @N 참조가 포함됩니다. 현재 셸 세션에 대해 완성을 활성화하려면:

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

bourne show 및 bourne compare의 완성은 BOURNE_DB를 포함하여 현재 구성된 데이터베이스를 쿼리합니다.

Bourne이 기록하는 것

모든 실험은 다음을 기록합니다:

• 실행 상태(completed, failed, interrupted), 정확한 인자 벡터, 작업 디렉터리, UTC 타임스탬프, 기간, 종료 코드;

• 실시간 및 캡처된 stdout/stderr;

• 가능한 경우 Git 저장소 루트, 커밋, 브랜치, 더티 상태;

• 운영 체제, 아키텍처, 호스트 이름, CPU, 선택적 NVIDIA 런타임 메타데이터;

• 요청 및 해석된 실행 파일 경로와 엄격히 허용 목록에 포함된 virtualenv/Conda 컨텍스트 힌트;

• 명시적으로 선언된 입력/출력 아티팩트 버전 및 직접 계보.

수집기는 우아하게 저하됩니다. Git, NVIDIA 도구, GPU, 환경 힌트 또는 실행 파일 해석이 없어도 워크로드는 중단되지 않습니다. 임의의 환경 변수는 저장되지 않으므로 자격 증명과 토큰은 기본적으로 캡처되지 않습니다.

실패 및 중단된 명령은 bourne이 프로세스 의미론을 반환하기 전에 저장됩니다:

bourne run --output expected.csv -- python -c "raise RuntimeError('boom')"
bourne show @1

POSIX 시스템에서 Bourne은 전용 프로세스 그룹을 사용하므로 Ctrl+C는 일반적으로 관련 없는 프로세스를 대상으로 하지 않고 하위 프로세스를 종료합니다.

실행 성공은 검증이 아니며, 결정적 아티팩트 검증은 일반적인 과학적 타당성이 아닙니다. Bourne은 이러한 상태를 별도로 기록합니다.

로컬 저장 및 마이그레이션

기본 SQLite 경로는:

~/.local/share/bourne/experiments.sqlite3

프로젝트별 데이터베이스를 사용하려면:

export BOURNE_DB=/path/to/experiments.sqlite3

이 릴리스 후보로 v0.1.1, v0.2.0, v0.3.0 또는 v0.4.0 데이터베이스를 열면 스키마 5까지 결정적 트랜잭션 마이그레이션이 수행됩니다. 기존 실험, 아티팩트, 계보, 인벤토리, 워크로드, 계획, 실행, 스케줄러 작업, 할당, 이벤트 및 실험 링크는 계속 읽을 수 있습니다. 마이그레이션은 v0.4 레코드에 대해 ExecutionRequest 기록을 만들어내지 않습니다. 알 수 없거나 최신 스키마 버전은 명시적으로 실패합니다. Bourne은 기존 데이터베이스를 재설정하지 않습니다. 각각의 새 발견은 별도의 불변 스냅샷을 생성합니다.

라이선스

Project Bourne v0.5.0 이상은 Apache License 2.0에 따라 배포됩니다. v0.4.0까지의 릴리스는 배포 당시의 MIT 라이선스 조건에 따라 유지됩니다. 자세한 내용은 라이선스 이력을 참조하세요.

릴리스 검증

저장소 버전은 0.6.0입니다. 기본 런타임에는 타사 종속성이 없습니다. MCP 지원은 명시적 선택적 추가 기능으로 유지됩니다.

소스 트리 테스트를 실행하려면:

PYTHONPATH=src python -W error::ResourceWarning -m unittest discover -s tests -v

stdout과 stderr는 최종 영속화 전에 여전히 메모리에 누적됩니다. 디스크 스풀링 실험 로그, 자동 아티팩트 검색, 아티팩트 보관, 자동 과학적 의존성 설치, 자동 모듈 로딩, 컨테이너 오케스트레이션, SSH 실행, 원격 복사, 활용도 샘플링, 프로파일링, 임의 검증 스크립트, 광범위한 과학적 타당성 추론, 호스팅 HTTP MCP, 임베디드 LLM, 자연어 파싱은 v0.6.0 범위 밖에 있습니다. 장기적인 방향은 docs/VISION.md를 참조하세요.