# The CTH Framework: A Functional Real-World Psychohistory

![BANNER](docs/banner.png)

[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/) [![Academic Paper](https://img.shields.io/badge/Paper-Academia.edu-blue.svg)](https://www.academia.edu/143241159/The_Tetrasociohistorical_Context_A_Quantitative_Model_for_the_Analysis_of_Historical_Events) [![Field: Cliodynamics](https://img.shields.io/badge/Field-Cliodynamics-red.svg)](#) [![Node.js](https://img.shields.io/badge/Node.js-v18%2B-green.svg)](https://nodejs.org/)

- 🌐 Website **[cthmodules.cc](https://www.cthmodules.cc)**
- 🔌 CTHmodules **[Official API](https://rapidapi.com/alejomalia/api/cthmodules/)**
- 📑 Paper **[The Tetrasociohistorical Context: A Quantitative Model for the Analysis of Historical Events](https://www.academia.edu/143241159/The_Tetrasociohistorical_Context_A_Quantitative_Model_for_the_Analysis_of_Historical_Events)**

**The transition from descriptive history to predictive civilizational engineering.**
* 🏛️ **Now the PAST into auditable data.**
* 🧬 **Now the PRESENT into a technical diagnosis.**
* ✨ **Now the FUTURE into a manageable probability.**

**The CTH Framework** is an advanced computational system designed to quantify, simulate, and predict the stability and transitions of large-scale socio-historical systems. By integrating **Shannon Entropy**, **Non-linear Dynamics**, and **High-Density Monte Carlo Simulations**, CTH provides a functional realization of the goals proposed by Isaac Asimov’s Psychohistory, translated into a rigorous 21st-century mathematical architecture.

---

## 🚀 Key System Features

* **📡 Strategic Orchestrator (`Core.js`):** The central synthesis unit. It integrates multi-dimensional sub-processes to define historical trajectories with 99.7% certainty.
* **🦋 Butterfly Field Logic:** High-density mapping of non-linear causal drifts and systemic ripples in real-time.
* **🛡️ Systemic Resilience:** Internal `ChaosShield` suite. Calculates structural recovery velocity and stability thresholds post-disruption.
* **🤖 Cognitive Bridge (`Bridge.js`):** Autonomous translation layer. Converts raw historical narratives into high-precision, structured analytical data.
* **📉 ΔCTH Inference System:** Dynamic weighting and Monte Carlo refinement to maintain analytical integrity within fragmented datasets.
* **🎭 Invariance Detection:** Automated identification of high-impact `Constructors` and absolute AlphaBreak threshold boundaries.

---

## 🏛 Core Methodology: The Architecture of Context

![BANNER](docs/scheme.png)

The **Tetrasociohistorical Context (CTH)** is a quantitative index designed to evaluate the historical, social, economic, and demographic conditions surrounding an event at a specific moment. It operates on the premise that an event's relevance is inseparable from its environmental context.

#### The Four Dimensions of CTH
The index is constructed from four main dimensions, each normalized to ensure proportional contribution:
* **Historical Epoch (E):** Captured through metrics like GDP per capita, Gini inequality, and political event density.
* **Social Range (S):** Based on average income and literacy rates.
* **Age Range (A):** Reflecting life expectancy and birth rates.
* **Population Range (P):** Analyzing population density and urbanization rates.

#### Dynamic Weight Adjustment & Resilience
A critical feature of the CTH Framework is its ability to handle **incomplete historical datasets**. If data for a specific dimension is missing (e.g., political records for a remote era), the system dynamically redistributes the weights to prevent distortions, ensuring the integrity of the analysis.

---

## ⚙️ The Analytical Engines

The framework is architected into specialized engines that process complexity, noise, and causal drift in human systems.

#### 1. Stochastic Projection Engine
* **Master Predictor Engine:** The central arbiter that synthesizes data from all sub-modules to deliver a final trajectory with 99.7% statistical confidence.
* **Monte Carlo Core:** Executes up to 50,000 iterations per phase to map the probability flow of civilizational outcomes.
* **CMN/RMD Analysis:** Classifies transitions into **Systemic Collapse (CMN)** or **Adaptive Transformation (RMD)**.

#### 2. Chaos & Resilience Architecture
* **Chaos Detection Engine:** Quantifies phase entropy using Shannon metrics to identify when a system enters a "non-deterministic" or chaotic regime.
* **ERI (Emergency Response Index):** Measures the kinetic recovery speed and resilience of a society after a Black Swan event.
* **Bivariate Interaction Engine:** Models non-linear couplings between dimensions (e.g., how economic decline triggers demographic shifts or political revolutions).

#### 3. The Seldon Bridge (AI Integration)
* **CTH-BRIDGE-AI.JS:** An autonomous layer that bridges the mathematical core with Large Language Models (LLMs).
* **Natural Language Processing:** Translates raw historical narratives and real-time global news into structured CTH data points.
* **Dynamic Calibration:** Allows the system to act as a "Psychohistorical Monitor," adjusting predictions in real-time as global data is ingested.

---

## 🚀 Getting Started

### Installation
```bash
npm install cthmodules
```

### Basic Implementation
```javascript
const { MasterPredictor } = require('cthmodules');

// Initialize the engine with societal metrics
const analysis = MasterPredictor.analyzeTrajectory(inputData);

console.log(`Global Stability Index: ${analysis.cth_global}`);
console.log(`Structural Singularity Risk: ${analysis.singularity_risk}%`);
```

---

## 🔌 CTHmodules API (Public Access)

The **CTH Psychohistorical Framework** is now available for developers, analysts, and AI agents via our official API. Integrate high-certainty predictive logic into your own systems.

#### 💳 Available Plans
* **The Explorer:** $9.99/mo | Ideal for individual testing.
* **The Strategist:** $49.00/mo | Professional grade analysis.
* **The Institutional:** $99.00/mo | High-volume data processing.
* **The Foundation:** $299.00/mo | Full-scale framework integration.

#### 🛠 Quick Integration
You can connect to the engine using any language (Python, JS, Go, etc.) through the RapidAPI Gateway.

**Official Endpoint:** `https://cthmodules.p.rapidapi.com/v1/predict/`

* 🔌 **[Get your API Key & Documentation here](https://rapidapi.com/alejomalia/api/cthmodules/pricing)**
* 🌐 **[Main Platform: Documentation, pricing, and theory](https://www.cthmodules.cc)**

#### 🧬 Commitment to Evolution
100% of the revenue generated through these plans is directly reinvested into the **CTH Framework**. 

---

## 🤝 Research & Collaboration

The CTH Framework is currently seeking collaboration with elite research institutions (specifically the Santa Fe Institute) to scale its "Butterfly Field Engine" onto high-performance computing clusters and quantum architectures.

* 🧠 Lead Architect **Alejo Malia**
* 🌐 Website **[cthmodules.cc](https://www.cthmodules.cc)**
* 📑 Paper **[The Tetrasociohistorical Context: A Quantitative Model for the Analysis of Historical Events](https://www.academia.edu/143241159/The_Tetrasociohistorical_Context_A_Quantitative_Model_for_the_Analysis_of_Historical_Events)**
* 👁 Visión "_You can't connect the dots looking forward; you can only connect them looking backwards. So you have to trust that the dots will somehow connect in your future._" - Steve Jobs

---

### License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License (CC BY-NC-SA 4.0). © 2023-2026 Alejo Malia. All rights reserved. Intellectual Property Registered (No. 2505091695916).

[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/) [![Terms of Use](https://img.shields.io/badge/Terms%20of%20Use-lightgrey.svg)](./WEIGHTS—TERMS_OF_USE.md)
