<div align="center">

# 🌌 EGen Core 
**The Recurrent-Depth Architecture Family**

[![Lab](https://img.shields.io/badge/Laboratory-EGen__Labs-4b0082.svg?style=for-the-badge)]()
[![Status](https://img.shields.io/badge/Status-Phase__1__Pretraining-0052cc.svg?style=for-the-badge)]()
[![Architecture](https://img.shields.io/badge/Architecture-LoopLLM / SPIRAL-007a5a.svg?style=for-the-badge)]()
[![License](https://img.shields.io/badge/License-Apache__2.0-blue.svg?style=for-the-badge)](LICENSE)

*“One block. Twelve iterations. The first axiom of EGen Core.”*

[**English**](README.md) | [**Français**](README.fr.md) | [**العربية**](README.ar.md)

</div>

---

**EGen Core** is a next-generation AI architecture family designed, built, and trained from the ground up by **EGen Labs**, an independent AI research organization directed by **ErebusTN**. 

This codebase represents a complete departure from traditional transformer scaling laws. Rather than indiscriminately stacking feed-forward layers to increase capacity, EGen Core investigates the mathematical and computational elegance of **Recurrent Depth (LoopLLM)**: learning one universal block and applying it iteratively to refine latent representations.

---

## 📌 1. Project Overview & Phases

### The Philosophy
The dominant paradigm in Large Language Models relies heavily on **feed-forward depth** (e.g., stacking 32 to 96 layers). While effective, this is memory-inefficient and treats language as a rigid conveyor belt. EGen Core forces the network to learn **one highly generalized universal block**. This single block routes latent representations back through the exact same matrix iteratively. Weight-sharing across depth geometrically reduces parameter footprint while maintaining high reasoning capacity.

### Phase 0: AXIOM-1
**`EGen-Core/AXIOM-1`** is the foundational proof of concept. It leverages 135M active weights across 12 routing loops. It actively proves deep, stable, autoregressive training can survive recurrent recursion without loop collapse.

### Phase 1: SPIRAL (Future)
SPIRAL extends AXIOM-1's recurrent block with **Streaming Recurrence** and **Adaptive Computation Time (ACT)**, allowing the model to dynamically choose how many loops it needs per token based on complexity.

---

## 🔬 2. Technical Capabilities

AXIOM-1 features highly strict mathematical boundaries designed for extreme memory efficiency:

*   **Scale**: `d_model=512`, `heads=8q/2kv` (GQA), `d_ff=1365`
*   **Vocabulary**: `132,000` (Multilingual BPE)
*   **Precision**: Pure `bfloat16`. (`float16` strictly prohibited due to recursive overflow).
*   **Stability**: Features mid-loop renormalization and SwiGLU initializations explicitly scaled by `1 / sqrt(2 × num_loops)`.
*   **AirLLM Execution**: Capable of executing 12-layer deep reasoning off sub-4GB consumer GPUs through component-level offloading and dynamic INT8 quantization.

---

## 🛠️ 3. Usage & Documentation

EGen Core employs a rigorous three-phase pretraining pipeline (Warm Start, Full Depth, Adaptive Depth). 

Before any training can commence, the model **must** pass the strict **6-Rule `sanity_check.py`** to mathematically verify that recurrent backpropagation gradients flow flawlessly backwards through all 12 loop block iterations without decay.

For complete step-by-step instructions on running the sanity checks, training the model, and engaging AirLLM memory constraints, refer to the full technical guide:

👉 [**AXIOM-1 Comprehensive Usage Guide**](docs/AXIOM1_Comprehensive_Guide.md)

---

## 🏛️ 4. Governance & Community

EGen Labs operates under strict architectural compliance rules. The mathematical fragility of recurrent loops means unverified scaling leads to instant gradient failure.

We welcome academic collaboration and code contributions under our organization's governance rules:

*   **[Code of Conduct](CODE_OF_CONDUCT.md):** Our pledge to foster an open and welcoming research environment.
*   **[Contributing Guidelines](CONTRIBUTING.md):** The absolute architectural axioms you must follow before submitting a Pull Request.
*   **[Security Policy](SECURITY.md):** How to report vulnerabilities related to model weight execution and cache overflows.
*   **[License](LICENSE):** EGen Core is proudly open-source under the Apache 2.0 License.

**EGen Labs** | Directed by **ErebusTN**
