Metadata-Version: 2.4
Name: eon-schema
Version: 0.2.1
Summary: Shared eOn L0 Cap'n Proto SSoT, L1 job-config pydantic models, and L2 API specs for eon-akmc + pyeonclient
Project-URL: Homepage, https://github.com/TheochemUI/eOn
Project-URL: Documentation, https://github.com/TheochemUI/eOn/blob/main/packages/eon-schema/README.md
Project-URL: Repository, https://github.com/TheochemUI/eOn
Project-URL: Issues, https://github.com/TheochemUI/eOn/issues
Project-URL: Changelog, https://github.com/TheochemUI/eOn/blob/main/packages/eon-schema/CHANGELOG.md
Author-email: Rohit Goswami <rgoswami@ieee.org>
License: BSD-3-Clause
License-File: LICENSE
Keywords: AKMC,capnp,eOn,pydantic,pyeonclient,schema
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: rgpycrumbs
Requires-Dist: rgpycrumbs>=1.3; extra == 'rgpycrumbs'
Description-Content-Type: text/markdown

# eon-schema

**Shared schema package for both eon-akmc and pyeonclient.** One home for:

| Layer | Module | Role |
|-------|--------|------|
| **L0** | `eon_schema.ssot` | Cap’n Proto field graph (vendored from monorepo `schema/`) |
| **L1** | `eon_schema.config` | Full job-config pydantic models (`MainConfig`, `Metatomic`, `Config`, …) |
| **L2** | `eon_schema.api` / `fields` | In-process specs (`DimerSpec`, `NebSpec`, enums) |

Consumers:

- **eon-akmc** — depends on `eon-schema`; `eon.schema` re-exports L1 for Sphinx / legacy imports.
- **pyeonclient** — `pyeonclient[models]` pulls `eon-schema`; `pyeonclient.models` re-exports L2.

Do **not** re-author job models under `eon/` or duplicate L2 under `pyeonclient/`.

## Fat tree vs this package

| | Fat monorepo tarball | This PyPI package |
|--|----------------------|-------------------|
| Purpose | conda-forge `eon`, full C++/server builds | Shared Python schema for both clients |
| Cap’n Proto | Full monorepo including `schema/` | Vendored under `src/eon_schema/ssot/` |
| L1 models | Also present via `eon.schema` re-export | **Authoritative** under `eon_schema.config` |
| Feedstock | **Uses fat tarball only** | Not required for 0.2.x |

**L0 authoring** is monorepo `schema/eon_params.capnp`. After edits:

```bash
python tools/params_ssot/codegen.py
./packages/eon-schema/scripts/sync_ssot_into_package.sh
```

**L1 authoring** is `packages/eon-schema/src/eon_schema/config/models.py`.
Keep field parity with L0 for covered sections (`tests/test_params_ssot.py`).

See **[PUBLISHING.md](PUBLISHING.md)** for fat vs split release trains.

## Install

```bash
pip install eon-schema            # L0 + L1 + L2 (pydantic is a hard dep)
# monorepo:
pip install -e packages/eon-schema
```

## Quick use

```python
# L0
from eon_schema.ssot import capnp_path, load_catalog

# L1 (same objects as eon.schema.*)
from eon_schema.config import MainConfig, Metatomic, Config

# L2 (same objects as pyeonclient.models.*)
from eon_schema.api import DimerSpec
from eon_schema.fields import MinModeMethod, Accelerant

print(capnp_path())
print(MainConfig().job)
print(DimerSpec(method=MinModeMethod.improved, accelerant=Accelerant.gp).core_kwargs())
```

eon-akmc / Sphinx still use:

```python
from eon.schema import MainConfig, Metatomic  # re-export
```

pyeonclient still uses:

```python
from pyeonclient.models import DimerSpec, NebSpec  # re-export
```

## Layout

```text
src/eon_schema/
  ssot/          # L0 vendored Cap'n Proto + catalog
  config/        # L1 job-config models (models.py)
  fields/        # enums
  api/           # L2 DimerSpec, NebSpec
  _deps.py
```

## INI helpers (config write without eon-akmc)

```python
from eon_schema.config import (
    MainConfig,
    PotentialConfig,
    DimerConfig,
    write_models_ini,
    write_ini,
    hydrate_ini,
    unknown_ini_keys,
    defaults_from_catalog,
)

# L1 models → config.ini (Dimer L1 prefixes mapped to INI keys)
write_models_ini(
    "config.ini",
    MainConfig(job="saddle_search"),
    PotentialConfig(potential="lj"),
    DimerConfig(dimer_improved=True),
    extra={"Debug": {"write_movies": True}},
    validate=True,
)

# Or raw sections (rgpycrumbs-style) with L0 hydrate + key check
user = {"Main": {"job": "minimization", "temperature": 400}}
cfg = hydrate_ini(user, base_sections=["Main", "Optimizer"])
assert not unknown_ini_keys(cfg)
write_ini("config.ini", cfg)

print(defaults_from_catalog("Main")["job"])
```

Downstream: **rgpycrumbs** should depend on ``eon-schema`` for
``write_eon_config`` / seed_dimers / MLflow log_params instead of full eon-akmc.
