Metadata-Version: 2.4
Name: entro-engine
Version: 1.0.0
Summary: ENTRO-ENGINE: An Entropy Flow Regulator for Coupled Intelligence Systems
Author-email: Samir Baladi <gitdeeper@gmail.com>
License: MIT
Project-URL: Homepage, https://entro-engine.netlify.app
Project-URL: Repository, https://github.com/gitdeeper10/entro-engine
Project-URL: DOI, https://doi.org/10.5281/zenodo.19441032
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS.md
Dynamic: license-file


# 🔴 ENTRO-ENGINE — Entropy Flow Regulator for Coupled Intelligence Systems

> *"A single engine regulates itself. A fleet of engines requires a coordinator."*
> — Samir Baladi, April 2026

**ENTRO-ENGINE** is the fourth project of the **EntropyLab** research program (**E-LAB-04**).  
It advances from single-system entropy control to **multi-system entropy coordination** — distributing thermodynamic pressure across coupled subsystems under a shared global budget constraint.

---

## 📌 DOI & Badges

[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.19441032-blue.svg)](https://doi.org/10.5281/zenodo.19441032)
[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-darkred.svg)](https://python.org)
[![PyPI](https://img.shields.io/badge/PyPI-pip_install_entro--engine-red.svg)](https://pypi.org/project/entro-engine)
[![Builds on](https://img.shields.io/badge/Builds_on-ENTROPIA_E--LAB--01-darkred.svg)](https://doi.org/10.5281/zenodo.19416737)
[![Builds on](https://img.shields.io/badge/Builds_on-ENTRO--AI_E--LAB--02-darkred.svg)](https://doi.org/10.5281/zenodo.19284086)
[![Builds on](https://img.shields.io/badge/Builds_on-ENTRO--CORE_E--LAB--03-darkred.svg)](https://doi.org/10.5281/zenodo.19431029)
[![Web](https://img.shields.io/badge/Web-entropia--lab.netlify.app-red.svg)](https://entropia-lab.netlify.app)
[![Website](https://img.shields.io/badge/Website-entro--engine.netlify.app-red.svg)](https://entro-engine.netlify.app)
[![Status](https://img.shields.io/badge/Status-Active_Research-brightgreen.svg)]()

---

## 🌐 Official Website

**https://entro-engine.netlify.app**

---

## 🎯 Vision

Build a **coordination layer** for AI pipelines in which multiple entropy-generating subsystems share a common thermodynamic budget — ensuring that no single subsystem collapses under load while others operate at idle, and that corrective pressure is distributed **in proportion to each subsystem's entropy contribution**.

### The Core Shift

| Architecture | Scope | Objective |
|---|---|---|
| **ENTROPIA** (E-LAB-01) | Definition | Establish Ψ vocabulary |
| **ENTRO-AI** (E-LAB-02) | Measurement | Monitor & detect collapse |
| **ENTRO-CORE** (E-LAB-03) | Local Control | Stabilize single Ψ field |
| **ENTRO-ENGINE** (E-LAB-04) | **Coordination** | **Distribute pressure across coupled systems** |

---

## 🔬 Key Innovation

**Instead of:** Each subsystem independently minimizes its own entropy  
**ENTRO-ENGINE does:** Enforce a global entropy budget across all coupled subsystems

```

Ψ_total(t) = Ψ_scraper + Ψ_llm ≤ Ψ_budget   ∀t

```

The engine computes corrective signals proportional to each subsystem's entropy fraction:

```

u_i(t) = −α · ρ_i(t) · tanh(β · Δ(t))

```

Where:
- `ρ_i` = fractional entropy ratio (fairness principle)
- `Δ(t)` = global entropy pressure above budget
- `tanh` = saturation (prevents overcorrection)

---

## 📊 Architecture

```

entro-engine/
│
├── engine/                   # Core coordination engine
│   ├── controller.py         # ENTRO-ENGINE control law (Eq. 14)
│   ├── budget.py             # Entropy budget constraint (Eq. 9–11)
│   └── allocator.py          # Proportional allocation ratios (Eq. 12–13)
│
├── subsystems/               # Coupled subsystem models
│   ├── scraper.py            # Scraper entropy source (Eq. 1, 4, 6)
│   ├── llm_queue.py          # LLM processing queue (Eq. 2, 5, 7)
│   └── base.py               # Abstract subsystem interface
│
├── entropy/                  # Entropy formulation layer
│   ├── proxy.py              # Log-proxy functions: Ψ = log(1 + x)
│   ├── aggregator.py         # Global Ψ_total computation (Eq. 8)
│   └── normalizer.py         # Logistic normalization
│
├── pipeline/                 # Realistic pipeline simulation
│   ├── simulator.py          # Three-phase pipeline (warmup / surge / recovery)
│   ├── simulator_v9.py       # Balanced regime engine
│   └── simulator_v10.py      # Recursive attractor engine
│
├── reports/                  # Daily/Weekly/Monthly reports
│   ├── daily/                # Daily .txt reports
│   ├── weekly/               # Weekly summaries
│   ├── monthly/              # Monthly analyses
│   └── alerts/               # Alert logs
│
├── tests/                    # Unit & integration tests
│   ├── test_controller.py    # Controller tests (9/9 passed)
│   ├── test_allocator.py     # Allocator tests
│   └── test_integration.py   # Integration tests
│
├── data/                     # Simulation output datasets
│   └── simulation_runs/      # CSV trajectory files
│
├── docs/                     # Documentation
├── paper/                    # Research paper assets
├── AUTHORS.md
├── CHANGELOG.md
├── LICENSE
├── README.md
└── pyproject.toml

```

---

## ⚙️ Core Equations

| Eq. | Expression | Description |
|---|---|---|
| 6 | `Ψ_s(t) = log(1 + r_s(t))` | Scraper entropy proxy |
| 7 | `Ψ_l(t) = log(1 + q_l(t))` | LLM entropy proxy |
| 8 | `Ψ_total(t) = Ψ_s + Ψ_l` | Global entropy aggregate |
| 9 | `Ψ_total(t) ≤ Ψ_budget ∀t` | Budget constraint |
| 11 | `Δ(t) = Ψ_total(t) − Ψ_budget` | Entropy pressure |
| 12–13 | `ρ_i = Ψ_i / Ψ_total` | Proportional allocation ratios |
| **14** | **`u_i(t) = −α · ρ_i · tanh(β · Δ)`** | **ENTRO-ENGINE control law** |

---

## 📦 Installation

```bash
pip install entro-engine
```

From source:

```bash
git clone https://gitlab.com/gitdeeper10/entro-engine.git
cd entro-engine
pip install -e .
```

---

🚀 Quick Start

```python
from entro_engine import ENTROEngineController

# Initialize controller
controller = ENTROEngineController(alpha=0.5, beta=2.0, psi_budget=3.0)

# Compute control signal
signal = controller.compute_control(psi_i=1.5, psi_total=4.0)

print(f"u = {signal.u:.3f}")
print(f"ρ = {signal.rho:.3f}")
print(f"Δ = {signal.delta:.3f}")
```

---

📈 Simulation Results

Validated on a three-phase realistic pipeline (warmup → surge → recovery):

Metric Uncontrolled ENTRO-ENGINE Improvement
Budget violations 312 / 1000 12 / 1000 96.2% reduction
Peak Ψ_total 5.84 3.31 43.3% reduction
Peak LLM queue 87.6 req 23.4 req 73.3% reduction

Regime Distribution (v9 Final Run)

Regime Count Percentage
🟢 Stable 24 30.0%
🟡 Stress 19 23.75%
🔴 Critical 37 46.25%

---

🔗 Links

Resource URL
🌐 Official Website https://entro-engine.netlify.app
📊 Dashboard https://entro-engine.netlify.app/dashboard
📚 Documentation https://entro-engine.netlify.app/documentation
📋 Reports https://entro-engine.netlify.app/reports
🦊 GitLab (Primary) https://gitlab.com/gitdeeper10/entro-engine
💻 GitHub (Mirror) https://github.com/gitdeeper10/entro-engine
📦 PyPI https://pypi.org/project/entro-engine
📌 DOI https://doi.org/10.5281/zenodo.19441032
🔴 ENTROPIA (E-LAB-01) https://doi.org/10.5281/zenodo.19416737
⚙️ ENTRO-AI (E-LAB-02) https://doi.org/10.5281/zenodo.19284086
🧠 ENTRO-CORE (E-LAB-03) https://doi.org/10.5281/zenodo.19431029
👤 ORCID https://orcid.org/0009-0003-8903-0029

---

🗺️ EntropyLab Research Program

Project Title Status DOI
E-LAB-01 ENTROPIA: Thermodynamic-Information Unification ✅ Published 10.5281/zenodo.19416737
E-LAB-02 ENTRO-AI: Entropy-Resistant AI Architectures ✅ Published 10.5281/zenodo.19284086
E-LAB-03 ENTRO-CORE: Self-Regulated Intelligence ✅ Published 10.5281/zenodo.19431029
E-LAB-04 ENTRO-ENGINE: Entropy Flow Regulator ✅ Published 10.5281/zenodo.19441032
E-LAB-05 ENTRO-FIN: Financial Market Entropic Signatures 📋 Planned —
E-LAB-06 ENTRO-SOCIAL: Social Network Information Cascades 📋 Planned —
E-LAB-07 ENTRO-QUANTUM: Quantum Extension 📋 Planned —
E-LAB-08 ENTRO-BIO: Biological Neural Networks 📋 Planned —
E-LAB-09 ENTRO-MANIFESTO: Unified Research Manifesto 📋 Planned —

---

📄 Citation

```bibtex
@software{baladi2026entroengine,
  author    = {Baladi, Samir},
  title     = {ENTRO-ENGINE: Entropy Flow Regulator for Coupled Intelligence Systems},
  year      = {2026},
  version   = {1.0.0},
  doi       = {10.5281/zenodo.19441032},
  url       = {https://gitlab.com/gitdeeper10/entro-engine},
  note      = {E-LAB-04. Builds on E-LAB-01, E-LAB-02, E-LAB-03}
}
```

---

📜 License

MIT License — Copyright © 2026 Samir Baladi

---

Part of the EntropyLab ten-project research program
"Intelligence by Design, Stability by Physics"
