Metadata-Version: 2.4
Name: epi-sigillin
Version: 1.0.0
Summary: Epigenetic runtime parameter mutation for the GenesisAeon UTAC/CREP framework
Project-URL: Homepage, https://github.com/GenesisAeon/epi-sigillin
Project-URL: Repository, https://github.com/GenesisAeon/epi-sigillin
Project-URL: Documentation, https://genesisaeon.github.io/epi-sigillin
Project-URL: Issues, https://github.com/GenesisAeon/epi-sigillin/issues
Project-URL: Zenodo, https://doi.org/10.5281/zenodo.XXXXXXX
Author: Johann Römer
License: MIT
License-File: LICENSE
Keywords: crep,criticality,entropy,epigenetics,genesisaeon,utac
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Description-Content-Type: text/markdown

# epi-sigillin

**Epigenetic runtime parameter mutation** for the GenesisAeon UTAC/CREP framework.

[![CI](https://github.com/GenesisAeon/epi-sigillin/actions/workflows/ci.yml/badge.svg)](https://github.com/GenesisAeon/epi-sigillin/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Analogous to how environmental signals alter gene expression without
changing the underlying DNA sequence, `epi-sigillin` lets a system's
entropy level "methylate" (suppress) or "de-methylate" (activate) CREP
tensor components — and rewrite CREP-YAML parameter files — at runtime.
This turns the otherwise static Sigillin narrative→CREP interface into a
dynamic, self-adapting one.

---

## Installation

```bash
pip install epi-sigillin
```

## Usage

```python
from epi_sigillin import EpiSigillin

system = EpiSigillin(seed=42)

# Run 100 epigenetic mutation cycles driven by a synthetic entropy trajectory
summary = system.run_cycle(duration_cycles=100)

print(summary["final_crep_state"])     # {"C", "R", "E", "P", "Gamma"} (effective)
print(system.methylation_state())      # {"C", "R", "E", "P"} methylation levels
print(system.get_phase_events())       # histone-mark transition events

# Rewrite a CREP-YAML file based on the current entropy level
system.mutate_yaml("crep_params.yaml", entropy_level=0.9)

# Inherit 50% of a parent cycle's methylation state into a new cycle
system.inherit_from(summary["methylation_state"])
```

### Diamond Interface

`EpiSigillin` implements the GenesisAeon Diamond-Template contract used
across the ecosystem:

| Method | Returns |
|---|---|
| `run_cycle(duration_cycles)` | Run cycles, return a summary dict |
| `get_crep_state()` | `{C, R, E, P, Gamma}` (effective, post-methylation) |
| `get_utac_state()` | `{H, dH_dt, H_star, K_eff}` |
| `get_phase_events()` | List of histone-mark transition events |
| `to_zenodo_record()` | Zenodo-ready metadata record |

Plus package-specific extensions: `methylation_state()`, `mutate_yaml()`,
`inherit_from()`.

## Epigenetic UTAC mapping

| UTAC symbol | Maps to |
|---|---|
| `H(t)` | System entropy level `S_total` (Shannon entropy of CREP state) |
| `K` | `S_max` — maximum sustainable entropy before destabilisation |
| `H*` | `S_optimal` — target entropy for stable self-organisation |
| `σ` | CREP coupling constant, `2.2` |

**Methylation rule** (suppression, `H(t) > H*`):
`P_effective = P · exp(-α · (H - H*) / K)`

**De-methylation rule** (activation, `H(t) < H*`):
`E_effective = E · (1 + β · (H* - H) / K)`

**Histone modification analogy:** `H3K4me3` (activation) ↔ high `E`
activation during low entropy; `H3K27me3` (repression) ↔ `P` suppression
during high entropy; `H3K9me3` (heterochromatin) ↔ complete CREP freezing
("crisis mode").

`epi-sigillin` has no fixed `Γ` of its own — it is the `Γ`-modulator for
every other GenesisAeon package: `Γ_epi = f(S_total)`, dynamic by design.

## Role in the GenesisAeon Ecosystem

`epi-sigillin` is **Package 28 (P28)** in the GenesisAeon ecosystem, domain
**epigenetics**, scale **systemic**. It sits above the other domain
packages, modulating their CREP tensors rather than producing one of its
own — the epigenetic-computational bridge between the static Sigillin
narrative interface and the live genesis-os runtime.

## Development

```bash
git clone https://github.com/GenesisAeon/epi-sigillin.git
cd epi-sigillin
pip install -e ".[dev]"
pytest --cov=src
ruff check src tests
mypy src
```

## Citation

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.PLACEHOLDER.svg)](https://doi.org/10.5281/zenodo.PLACEHOLDER)

DOI will be assigned automatically on first GitHub Release once
Zenodo–GitHub integration is enabled for this repo.

Reference: Greenberg, M.V.C. & Bourc'his, D. (2019). The diverse roles of
DNA methylation in mammalian development. *Nature Reviews Molecular Cell
Biology* 20, 590–607. DOI: [10.1038/s41580-019-0160-9](https://doi.org/10.1038/s41580-019-0160-9)
