Project Bourne

Project Bourne es una infraestructura de código abierto de ejecución y procedencia para cargas de trabajo científicas y de ingeniería reproducibles.

Planifica y ejecuta experimentos computacionales en equipos locales, GPUs, Slurm y PBS, a la vez que conserva entradas, salidas, contexto de ejecución, linaje de artefactos, telemetría, verificación e historial necesarios para reproducir un resultado.

Está diseñado para investigadores, estudiantes desde el grado hasta el doctorado, profesorado, ingenieros de investigación, científicos computacionales, usuarios de software científico y equipos de computación científica, tanto en el ámbito académico, como en la investigación pública y en la industria I+D.

Inicio rápido

Humano

La CLI para humanos está disponible hoy:

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

Agente / MCP

Los puntos de entrada de agente y MCP de la v0.6.0 son públicos:

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

Para desarrollo desde la copia del código fuente, en lugar de eso:

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

Related MCP server: heddle

Por qué Bourne

Bourne encapsula ejecutables arbitrarios sin necesidad de cambiar el programa científico. Es local-first y agnóstico respecto al framework: Python, solvers compilados, Julia, programas MPI y otros comandos usan el mismo modelo de experimento duradero.

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

Los stdout y stderr del programa permanecen visibles durante la ejecución y se conservan en el registro del experimento.

Arquitectura

Bourne Core es responsable de la ejecución determinista, la planificación, el almacenamiento y la procedencia. Los humanos pueden usarlo mediante la CLI o servicios de Python; los agentes pueden usar los mismos servicios a través del adaptador opcional de MCP:

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

La interfaz de agente es una vía opcional de acceso, no la identidad de producto de Bourne. MCP funciona sin la Skill portable, y Bourne no contiene ningún LLM integrado.

Integración de agente y MCP

El servidor stdio local canónico es bourne mcp. La identidad oficial estable del Registro MCP es io.github.KozakHou/project-bourne, y la Skill de agente portable está en skills/project-bourne. El paquete npm v0.6.0 y la entrada correspondiente del Registry son públicos.

Un agente compatible con MCP puedes convertir una solicitud explícita como "Ejecuta esta simulación con cuatro GPUs y conserva la procedencia" en una ExecutionRequest v1, pedir a Bourne que la planifique, mostrar la resolución determinista y ejecutar el plan inmutable cuando se haya establecido la intención de ejecución. Bourne no interpreta lenguaje natural sin restricciones y no llama a otro modelo.

La vía de agente es deliberadamente bifásica:

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

La planificación nunca ejecuta la carga de trabajo ni descubre infraestructura de forma silenciosa. Los objetivos ambiguos y los hechos desconocidos permanecen sin resolver. Las anotaciones MCP son sugerencias de UX del host: Bourne Core sigue aplicando planes inmutables, argv exacto, propiedad de jobs del planificador, semántica de artefactos y procedencia. Consulta Integración con MCP y Guía de agentes.

Solicitudes de ejecución

Una ejecución ahora puede describirse en una solicitud JSON delimitada y versionada:

{
  "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}
    ]
  }
}

Guárdalo como bourne.json y usa la misma intención para planificar o ejecutar:

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

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

Crea una solicitud mínima sin ejecutar ni descubrir nada:

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

Los comandos actuales basados en flags siguen siendo compatibles. Se compilan en el mismo pipeline ExecutionRequest → WorkloadSpec → ExecutionPlan, en lugar de una implementación en paralelo:

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

Para un archivo de solicitud, una working_directory relativa se resuelve desde el directorio del archivo de solicitud. Los artefactos declarados se resuel then a partir de ese directorio de trabajo científico. Bourne conserva los valores léxico y derivado del directorio de trabajo, y no expande $HOME, no evalúa sintaxis de shell, no importa código del proyecto ni ejecuta nada mientras analiza o planifica.

Las referencias parentales siguen la misma regla de preservación de la intención. Una solicitud puede usar latest, @N, un nombre único o un ULID completo. Bourne conserva ese valor solicitado y registra aparte el ULID canónico del padre usado por la carga de trabajo compilada.

La telemetría resumida está habilitada por defecto y usa hechos ya capturados: wall time, recuentos de bytes UTF-8 de stdout/stderr, totales de bytes de artefactos conocidos, recursos solicitados, asignación observada y tiempos de cola del scheduler cuando los timestamps lo permiten. "telemetry": {"mode": "off"} desactiva el resumen. Los hechos que faltan siguen estando disponibles, nunca son cero.

Las comprobaciones iniciales de verificación determinista son output_exists, output_min_bytes, y output_sha256. Evalúan solo los registros Artifact de salida como capturados. La verificación se guarda aparte del estado de proceso: un experimento puede estar completed mientras la verificación está failed o unknown. Estas comprobaciones establecen hechos sobre un artefacto, no validez científica general. Consulta Solicitudes de ejecución , telemetría y verificación para saber el contrato exacto y los límites de seguridad.

Planificación y ejecución

Project Bourne v0.4.0 añade una capa de planificación duradera sobre los inventarios 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 nunca ejecuta el comando científico ni hace discovery. Crea un WorkloadSpec independiente del framework, compara sus requisitos implícitos y explícitos con un inventario existing, explica cada candidato y conserva un ExecutionPlan inmutable solo cuando la selección no sea ambigua. Usa restricciones de recursos y colocación cuando sea necesario:

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

Ejecuta un plan de Slurm seleccionado y luego inspecciona o espera el intento de ejecución resultante:

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

Mientras un job grabado sigue activo, bourne execution cancel @1 solicita la cancelación de esa task gestionada por Bourne. El mismo modelo de planificación y ciclo de vida admite --backend pbs.

La ejecución directa reutiliza la maquinaria existente de Bourne: live output, process group, artifacts, lineage y provenance. Los planes Slurm y PBS usan un worker de Bourne autónomo preparado con el plan. El worker hace pre notificación y registra el host y the experimental experiment actualmente asignados: el controlador del lado de acceso importejec sudario JSON limitado de forma transaccional. No se requiere SSH a nodos de cómputo ni paquete bourneprov preinstalado, aunque la vitacora de cómputo debe provide Python 3 y visibilidad de los directorios de apoyo y de trabajo.

Enviar no es un experimento, la finalización del scheduler no es un éxito científico, y los recursos solicitados no son recursos asignados. Bourne registra estados duraderos por separado. La cancelación acepta una referencia de ejecución de Bourne, no un ID arbitrario de job del scheduler, y comprueba la identidad del que envía. Consulta Planificación de cargas de trabajo y ejecución con scheduler para conocer el modelo exacto, el límite de seguridad y las limitaciones actuales.

Descubrimiento de sitios de compute (v0.3.0)

Bourne puede tomar una instantánea local e inmutable de la superficie de ejecución visible para tu identidad actual:

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

El descubrimiento abarca la identidad y el target de acceso actual, rutas de almacenamiento relevantes permitidas, contextos de ejecución directa, ejecutables PATH genéricos, contextos coConda/virtualenv/container/module, capacidades seguras del sistema, historial de Bourne y resúmenes de clase de destino Slurm/PBS de solo lectura cuando existan. Un ejecutable desconocido se registra de manera genérica sin ser ejecutado. Laptops, estaciones de trabajo de escritorio y GPU, máquinas personales clase DGX, sistemas de laboratorio compartidos y sitios HPC respaldados por queues son todos sitios de compute válidos. Una máquina sin scheduler está completa por sí misma.

El descubrimiento es observacional: un ejecutable no es validado para compatibilidad con la carga de trabajo, una partición del work o ejecución visible no es prueba, no es una autorización de envío, y una hint de rol de almacenamiento no es una política de retención ni de backups. Los inventarios permanecen locales. Los providers no atraviesan los home de otros usuarios, no recorren storage compartido, no inspeccionan credenciales SSH ni secretos de contenedores, no evacúan variables de entorno arbitrarias, no hacen SSH a nodos de cómputo, no envían ni cancelan trabajos del scheduler, ni modifican entornos. Consulta Descubrimiento de sitios de cómputo para conocer la topología exacta, las evidencias, los límites y las semillas de seguridad.

Procedencia, Artefactos y Linaje

Project Bourne v0.2 añade huellas explícitas de entrada/salida, una relación mínima derived_from, observaciones seguras de contexto de ejecución y el rastreo de artefactos. Ejecuta el ejemplo determinista desde un directorio aislado:

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

Las entradas se marcan con huellas antes de la ejecución. Las salidas se marcadas despues, incluyendo las esperanzas que faltan después de una ejecución falllastid o interrumpida. SHA-256 se lee en bloques; no se notifica ni copia ni exporta aplicaciones de archivos declarados.

Una ruta no es una identidad de artefacto. Cada captura tiene un ULID único, mientras que SHA-256 distingue las versiones del contenido. Cuando un historial puede identificar varias versiones y el contenido actual del archivo no las puede distinguir, bourne trace muestra candidatos y rechaza a interpretar. Ver Artifacts, lineage, and execution context para la semántica exacta de captura, rastreo, migración y seguridad.

Referencias de experimentos amigables para humans

Las identidades canónicas de experimentos siguen siendo ULIDs de 26 caracteres. Los comandos aceptan a furtivo, use an experiment also discover:

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

Por ejemplo:

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

Bourne nunca adivina si un prefijo es ambiguo. bourne list muestra un prefijo de 10 caracteres por defecto; bourne list --full-id muestra los IDs canónicos.

Autocompletado de shell

Los candidatos de autocompletado incluyen IDs canónicos de experimento, latest, y referencias recientes @N. Activar la completado para la sesión de shell actual con:

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

O auto para bourne show y bourne compare consulta la base de datos configurada actual, incluido BOURNE_DB.

Lo que Bourne registra

Cada experimento registra:

• estado de ejecución (completed, failed o interrupted), vector de argumentos exacto, working directory, marcas de tiempo UTC, duración y código de salida;.* stdout/stderr en vivo y capturados;* raíz del repositorio Git, commit, rama y dirty state si existe;

• sistema operativo, arquitectura, nombre de host, CPU y metadatos runtime de NVIDIA opcional;. * rutas de ejecutables solicitadas y resueltas, más indicaciones de contexto virtualenv/Conda estrictamente allow-listed;

• versiones de artefactos de entrada/salida declarados y herencia del linaje.

Los recolectores decaen con gracia. La falta de Git, herramientas de NVIDIA, GPUs, pistas de entorno o resolución sin errores no hace fallar la carga. Las variables de entorno arbitrarias no persisteten, así que las credenciales y tokens no estén capturados por defecto.

Los comandos fallidos e interrumpidos se guardan antes de que Bourne devuelva su semántica de proceso:

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

En sistemas POSIX, Bourne usa un grupo específico de proceso de proceso para suplente: normalmente termine los valores y sin to other procesos no relacionados.

La ejecución exitosa no es verificación, y la verificación determinista de artefactos no es validación científica general. Bourne guarda estos estados por separado.

Almacenamiento local y migración

La ruta ruta por defecto de SQLite es:

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

Usar una base específica del Proyecto:

export BOURNE_DB=/path/to/experiments.sqlite3

Abrir una base de data v0.1.1, v0.2.0, v0.3.0 o v0.4.0 con este release candidate ejecuta migraciones transaccionales deterministas hasta el esquerma 5. Los experimentos, artefactos, linaje, inventarios, workloads, planes, ejecuciones, jobs de scheduler, asignaciones, allocaciones, socias y enlaces de experimento siguen siendo legibles. La migración no echa creación de ExecutionRequest histórico de v0.4. Los esquemas desconocidos o más nuevos fallan explícitamente; Bourne nunca se reposiciona una base de data existente. Cada nuevo descubrimiento crea una instantánea inmutable nueva.

Licencia

La v0.5.0 y posteriores se distributed bajo la Apache License 2.0. Las versiones hasta la v0.4.0 permanecen bajo los términos de la Licencia MIT en virtud de los cuales se publicaron. Consulta historial de licencias para más detalles.

Validación de release

La versión del repositorio es 0.6.0. La base runtime tiene cero dependencias de terceros; el soporte MCP es una opción adicional explícitamente opcional.

Ejecuta las pruebas del árbol de fuentes con:

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

stdout y stderr todavía se acumulan en memoria antes de la persistencia final. Los registros de experimentos con spool en disco, el descubrimiento automático de artefactos, el archivado de artefactos, la instalación automática de dependencias científicas, la carga automática de módulos, la orquestación de contenedores, la ejecución SSH, la copia remota, el muestreo de utilización, la perfilación, los scripts de verificación arbitrarios, la inferencia amplia de validez científica, el MCP HTTP alojado, los LLM integrados y el análisis de lenguaje natural permanecen fuera de v0.6.0. Consulte docs/VISION.md para conocer la dirección a largo plazo.