Jarvis-Portal

Jarvis-Portal is the standalone IO adapter and registry package for the Jarvis ecosystem.

It provides format-specific read/write behavior for scientific file formats used by Jarvis-HEP and related tools.

Versioned product surfaces (adapters are shared; interface factories are not):

Shared IO implementations live under jarvis_portal.adapters. Do not call V1 factory functions from V2 code (or vice versa).

Jarvis-Portal is intended to serve YAML-driven Jarvis workflows through Jarvis-HEP. It does not own Jarvis-HEP YAML parsing or runtime workflow semantics.

Scope

Jarvis-Portal owns:

• format adapter registration and lookup
• JSON and Wolfram nested entry reads/writes
• CSV, TSV, and DAT table reads/writes
• plain-text input placeholder replacement and upstream-file copying
• future adapters for ROOT, HepMC, LHE, YODA, SPheno, MadGraph cards, and related HEP formats

Jarvis-HEP owns:

• YAML IO block parsing
• runtime path markers such as &J, @PackID, @SampleID, and @Sdir
• expression evaluation
• sample/runtime context
• save/copy/archive policy
• logger and IO manager integration
• deciding which variables are written or read
• plain file copy/save helpers that do not require format parsing

Quick Install

pip install Jarvis-HEP-Portal

Core dependencies include PyYAML, rich, pyslha, and xslha (no optional extras needed for SLHA/xSLHA). Legacy install tags [slha] / [xslha] / [all] remain as empty aliases.

Development

python -m pip install -e ".[dev]"
python -m pytest
ruff check .
python -m build

Basic Usage

CLI:

jportal file
jportal man
jportal man json
jportal -h
jportal -v

jportal file is the only supported business CLI shape. It prints the observable dictionary itself as JSON. Utility exceptions are jportal man, jportal man <format>, -h/--help, and -v/--version.

Python:

from jarvis_portal import IOContext, create_default_registry

registry = create_default_registry()
adapter = registry.get("JSON", "input")

def evaluate_expression(expression, values):
    if expression == "x * 2":
        return values["x"] * 2
    raise ValueError(expression)

context = IOContext(evaluate_expression=evaluate_expression)
observables = await adapter.write_input(
    context,
    {
        "name": "params",
        "path": "input.json",
        "type": "JSON",
        "actions": [
            {
                "type": "Dump",
                "variables": [
                    {"name": "nested", "entry": "config.value", "expression": "x * 2"},
                ],
            },
        ],
    },
    {"x": 1.0},
)

JSON adapter calls return the observable dictionary itself. For JSON input, plain dumped variables are written to the file; expression variables and saved file specs may contribute observables, matching Jarvis-HEP.

Documentation

• Docs index
• Changelog
• Development
• CLI
• Architecture
• Adapter authoring
• Format catalog
• JSON format usage
• Table formats usage (CSV/TSV/DAT)
• Wolfram format usage
• Testing
• Release
• Contributing

Status

This package is in alpha development. Runtime behavior should stay small and adapter-focused so Jarvis-HEP can remain the owner of workflow semantics.

Releasing

jptrel is a maintainer-local script, excluded from Git and distribution archives.

Record changes in CHANGELOG.md, then run from this checkout (replace the example version with the intended release):

./jptrel 1.5.3 --dry
./jptrel 1.5.3

--dry performs read-only source and release-note checks. The normal command requires a clean Git checkout, builds and checks the wheel and sdist, uploads to PyPI, refreshes the local version with python3 -m pip install -e ., and verifies the installed version. Only then does it commit the version, push the vX.Y.Z tag, and create a GitHub release with changelog notes. Configure Twine and gh authentication before publishing.