Metadata-Version: 2.4
Name: Jarvis-HEP-Portal
Version: 1.5.2
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: rich>=13.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: pyslha>=3.2.5
Requires-Dist: six>=1.16
Requires-Dist: xslha>=1.0.0
Provides-Extra: slha
Provides-Extra: xslha
Provides-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.

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

| Surface | Import | Default formats |
|---------|--------|-----------------|
| **V1** (top-level / `jarvis_portal.v1`) | `from jarvis_portal import create_entry_point_registry` | JSON, CSV, TSV, DAT, Wolfram, Text (input) |
| **V2** | `from jarvis_portal.v2 import create_entry_point_registry` | above **+ SLHA, xSLHA** |

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

```bash
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

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

## Basic Usage

CLI:

```bash
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:

```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](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)
- [Table formats usage (CSV/TSV/DAT)](docs/development/TABLE_FORMATS.md)
- [Wolfram format usage](docs/development/WOLFRAM_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.
