Project Bourne

Project Bourne — это открытая инфраструктура выполнения и контроля происхождения данных (provenance) для воспроизводимых научных и инженерных вычислительных задач.

Она планирует и выполняет вычислительные эксперименты на локальных машинах, GPU, в Slurm и PBS, сохраняя входные данные, выходные данные, контекст выполнения, происхождение артефактов, телеметрию, верификацию и историю, необходимую для воспроизведения результата.

Она предназначена для исследователей, студентов — от уровня бакалавриата до докторантуры, преподавателей, инженеров-исследователей, специалистов по вычислительной науке, пользователей научного программного обеспечения и команд научных вычислений в академической среде, государственных исследованиях и отраслевых R&D.

Быстрый старт

Для человека

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 оборачивает произвольные исполняемые программы без необходимости изменять научный код. Он локально-ориентированный и не зависит от фреймворков: 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. Пакет npm v0.6.0 и соответствующая запись в Registry публично доступны.

MCP-совместимый агент может преобразовать явный запрос, например: «Запусти эту симуляцию на четырёх GPU и сохрани provenance», — в ExecutionRequest v1, попросить Bourne спланировать его, показать детерминированное разрешение и выполнить неизменяемый план после установленного намерения выполнения. Сам Bourne не интерпретирует произвольный естественный язык и не обращается к другой модели.

Путь агента сознательно двухфазный:

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

Планирование никогда не выполняет рабочую нагрузку и не «обнаруживает» инфраструктуру молча. Неоднозначные цели и неизвестные факты остаются невыясненными. Аннотации MCP — это UX-подсказки хоста; Bourne Core по-прежнему обеспечивает неизменяемые планы, точный argv, владение задачами планировщика, семантику артефактов и provenance. См. интеграцию с MCP и руководство для агентов.

Запросы на выполнение

Выполнение теперь может быть описано один раз в ограниченном, версифицированном 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, не интерпретирует синтаксис оболочки, не импортирует код проекта и ничего не выполняет при разборе или планировании.

Ссылки на родительские объекты следуют тому же правилу сохранения намерения. Запрос может использовать latest, @N, уникальный префикс или полный ULID. Bourne сохраняет важное запрошенное значение отдельно от канонического родительского ULID, используемого скомпилированной рабочей нагрузкой.

Сводная телеметрия включена в false|251|default и использует уже захваченные факты: время ведущего времени (wall time), количество байт stdout/stderr в UTF-8, совокупные размеры известных артефактов в байтах, запрошенные ресурсы, фактическое распределение и тайминг очереди планировщика, если он эксплуатациями временными метками. "telemetry": {"mode": "off"} отключает сводку. Отсутствующие метрики остаются недоступными, но никогда не равны нулю.

Начальные детерминированные верификационные проверки — это output_exists, output_min_bytes и output_sha256. Они оценивают только захваченные записи объявленных выходных Artifact. Верификация хранится отдельно от статуса процесса: эксперимент может иметь статус completed, а верификация — продолжена или unknown. проверки устанавливают факты об артефактах, а не научную правильность в целом. Точный контракт и границы безопасности см. в разделе Execution requests, telemetry, and verification.

Planning и Execution

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 никогда не запускает научную команду и не обнаруживает инфраструктуру. Он создаёт независящий от фреймворка WorkloadSpec, сравнивает его явные и выведенные требования с существующей инвентаризацией, подробно объясняет каждого кандидата и сохраняет неизменяемый ExecutionPlan только тогда, когда выбор однозначен. При необходимости задайте явные ограничения ресурсов и размещения:

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

Выполните выбранный план SJTC Slurm, и затем просмотрите или дождитесь полученной попытки выполнения:

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

Пока записанная задача ещё активна, bourne execution cancel @1 запрашивает отмену этой управляемой орт. Также подходит для планирования и жизненного цикла поддерживает --backend. Процесс:

Compute-site discovery (v0.3.0)

Bourne может снять неизменяемый локальный кадр поверхности выполнения, видимой вашего текущей учётной записью:

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

Discovery покрывает текущую учётную запись и цель доступа, разрешённые и имеющие отношение стора сто пользователя, прямые контексты исполнения, generic PATH executables, опциональные контексты Conda/virtualenv/container/module, безопасные системные возможности, историю Bourne и дополнительные только для чтения resumerals of Slurm/PBS, обеспечивают ли они задачи. Неизвестный executable хранится обобщённо, без его запуска. Ноутбуки, десктопы и GPU-станции, личные рабочие станции класса DGX, общие лабораторные системы и сайты HPC с бэкендом планировщика считаются полноценными вычислительными сайтами. Машина без планировщика самодостаточна и действительно удаленна.

Discovery наблюдается: сам факт наличия executable не является подтверждённой совместимостью, видимая парция scheduler — не является разрешением на отправку, и роль хранилища не является политикой хранения или резервного копирователя. Инвентаризации остаются локальными. Провайдеры не обходят чужие домашние каталоги, не сканируют общие хранилища, не проверяют SSH-секреты или секреты контейнеров, не выгружают произвольные переменные окружения, не SSH-подключены к вычислительным нодам, не посылают и не отменяют задачи планировщика и не модернизуют окружения. См. Compute-site discovery для точной топологии, обоснований, ограничений и семантики безопасности.

Provenance, Artifacts и Lineage

Project Bourne v0.2 добавляет явное входное/output отпечатки, минимальное производное lineage, безопасные наблюдения выполнения и tracing артефактов. Запустите детерминированный пример из изолированного каталога:

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 передает кандидатов и отказывается угадывать.

См. [Artifacts, lineage, and execution context](https://github.com/KozakHou/project-bout -|| asks/blob/main/docs/ARTIFACTS_AND_LINEAGE.md) для точной семантики захвата, 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 shows канонические идентичники.

Автодополнение

Кандидаты для автодополнения включают канонические идентигии экспериментов, latest и последующие ссылки на @N. Включите автополнение для текущей сессии:

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

Автодополнение для bourne show и bourne compare отправляет запрос к текущей сконфигурированной базе данных, включая GXP.

Что Bourne записывает

Каждый эксперимент записывает:

• статус исполнения completed, failed или interrupted, точный путь аргументов, время UTC, срок, рабочий каталог, продолжительность и код завершения;

• live и сохранённый stdout/stderr;

• корень Git-репозитория, коммит, ветку и "dirty" состояние, если доступно;

• операционную систему, архитектуру, hostname, CPU и дополнительную метадату NVIDIA;

• запрошенные и разрешённые пути к исполнимым ибtained executable segments и строго разрешённые подсказки virtualenv/conda;

• явно объявленные версии входных/выходных артефактов и ближайшее lineage.

Collectors работают с устойчивостью. Отсутствие Git, NVIDIA tools, GPU, environment hints или очков выполнения не останавливает работу. Произвольные переменные окружения и ключи (credentials, tokens) по умолчанию не персистятся.

Файлы после неудачных и прерванных команд сохраняются до того, как 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. υ.3.0 или v0.4.0 с этим рец визионным кандидатом выполняет детерминированное транзакционное смещение до схемы 5. Существующие эксперименты, артефакты, lineage, энventory, workloadты, планы, выполнение, задачи планировщика, аллокации, события и связи экспериментов остаются читаемыми. Миграция не добавляет фиктивную историю ExecutionRequest для v0.4. Неизвестные или более новые версии avier; откажется с явной ошибкой. Bourne никогда не сбрасывает существующие базу данных. Каждое новое обнаружение создает отдельную неизменяемую моментальную снимка.

Лицензия

The project Bourne v0.5.0 и выше распространяется под Apache License 2.0 . Выпуски вплоть до v0.4.0 остаются под MIT-лиценстрией, под которой они были опубликованы. См. history licenses.

Валидация релиза

Версия репозитория — 0.6.0. Базовая среда выполнения не имеет зависимостей от третьих edition; поддержка 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.