Metadata-Version: 2.4
Name: Jarvis-HEP-Portal
Version: 1.0.0
Summary: IO adapter registry and format backends for the Jarvis ecosystem
Author: Pengxuan Zhu
License-Expression: MIT
Project-URL: Homepage, https://github.com/Pengxuan-Zhu-Phys/Jarvis-Portal
Project-URL: Repository, https://github.com/Pengxuan-Zhu-Phys/Jarvis-Portal
Project-URL: Issues, https://github.com/Pengxuan-Zhu-Phys/Jarvis-Portal/issues
Keywords: HEP,physics,IO,Jarvis-HEP,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: slha
Requires-Dist: pyslha>=3.2.5; extra == "slha"
Provides-Extra: xslha
Requires-Dist: xslha>=1.0.0; extra == "xslha"
Provides-Extra: all
Requires-Dist: pyslha>=3.2.5; extra == "all"
Requires-Dist: xslha>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# 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, including JSON, plain files, SLHA, xSLHA, and future HEP calculator formats.

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 nested entry reads/writes
- plain file adapter helpers
- optional SLHA/xSLHA record handling
- 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

## Quick Install

```bash
pip install Jarvis-HEP-Portal
```

Optional format extras:

```bash
pip install "Jarvis-HEP-Portal[slha]"
pip install "Jarvis-HEP-Portal[xslha]"
pip install "Jarvis-HEP-Portal[all]"
```

## Development

```bash
python -m pip install -e ".[dev,all]"
python -m pytest
ruff check .
python -m build
```

## Basic Usage

CLI:

```bash
jportal input.yaml
jportal input.yaml --json
jportal --formats
jportal --version
```

By default, `jportal input.yaml` parses the YAML file and prints the resulting Python dictionary to the terminal. It does not execute Jarvis-HEP workflow semantics.

Python:

```python
from jarvis_portal import IOContext, create_default_registry

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

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

## Documentation

- [Docs index](docs/README.md)
- [Development](docs/development/DEVELOPMENT.md)
- [CLI](docs/development/CLI.md)
- [Architecture](docs/design/ARCHITECTURE.md)
- [Adapter authoring](docs/development/ADAPTER_AUTHORING.md)
- [Format catalog](docs/development/FORMAT_CATALOG.md)
- [JSON format usage](docs/development/JSON_FORMAT.md)
- [Testing](docs/development/TESTING.md)
- [Release](docs/release/RELEASE.md)
- [Contributing](CONTRIBUTING.md)

## 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.
