erh 0.1.0
Ethical Riemann Hypothesis (ERH) Simulation SDK
Requires Python: >=3.10

````markdown
# Ethical Riemann Hypothesis (ERH)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![Status](https://img.shields.io/badge/Status-Research_Preview-orange)](https://github.com/)

**A mathematical framework for analyzing moral judgment errors through an analogy with the Riemann Hypothesis in number theory.**

---

## 📖 Project Overview

This project introduces the **Ethical Riemann Hypothesis (ERH)**. It posits that in a "healthy" moral judgment system, the cumulative error in predicting critical misjudgments grows at most like $\sqrt{x}$, where $x$ is the complexity of the decision.

### Key Concepts

- **Ethical Primes ($P$)**: Critical misjudgments representing fundamental errors.
- **$\Pi(x)$**: The count of ethical primes up to complexity $x$.
- **$E(x) = \Pi(x) - B(x)$**: The error term comparing the actual count vs. the baseline expectation.
- **The ERH Condition**: $|E(x)| \leq C \cdot x^{1/2 + \epsilon}$ for healthy judgment systems.

### Analogy with Number Theory

| Number Theory Concept | Ethical Judgment Analogy |
| :--- | :--- |
| **Prime Numbers** | Ethical Primes (Critical Misjudgments) |
| **$\pi(x)$** | $\Pi(x)$ (Count of ethical primes) |
| **Prime Number Theorem** | Baseline Expectation $B(x)$ |
| **Riemann Hypothesis** | Ethical Riemann Hypothesis (Bounds on error growth) |

---

## 🖼️ Demo

Below are visualizations generated by the framework, showcasing the distribution of ethical primes and the behavior of the error term.

| Zeta Function Analysis | Error Distribution |
| :---: | :---: |
| ![Zeta Function Visualization](https://github.com/user-attachments/assets/86b7e910-dc49-4d9c-ab6e-bb8dd9dceb2a) | ![Error Distribution Plot](https://github.com/user-attachments/assets/f883510f-b0e5-479c-a792-a93b554618be) |

| Prime Counting Function $\Pi(x)$ | Critical Line Analysis |
| :---: | :---: |
| ![Prime Counting Function](https://github.com/user-attachments/assets/421f952c-a732-43fe-8049-6da2dba27e51) | ![Critical Line Analysis](https://github.com/user-attachments/assets/b1543552-036f-43b9-a35e-f058d8641683) |

---

## 📂 Project Structure

```text
Ethic-Latex/
├── simulation/                 # Python simulation framework
│   ├── core/                   # Core modules
│   │   ├── action_space.py     # Action and world generation
│   │   ├── judgement_system.py # Judge implementations
│   │   └── ethical_primes.py   # Prime selection and analysis
│   ├── analysis/               # Analysis tools
│   │   ├── zeta_function.py    # Ethical zeta function
│   │   └── statistics.py       # Statistical analysis
│   ├── visualization/          # Plotting utilities
│   │   └── plots.py            # All visualization functions
│   ├── notebooks/              # Jupyter notebooks for experiments
│   │   ├── 01_basic_simulation.ipynb
│   │   ├── 02_judge_comparison.ipynb
│   │   └── ... (other analysis notebooks)
│   └── output/                 # Generated figures and data
├── scripts/                    # Utility scripts
├── docs/                       # Documentation files
├── tests/                      # Test files
├── ethical_riemann_hypothesis.tex  # Main research paper (LaTeX)
└── requirements.txt            # Python dependencies
````

-----

## ⚡ Installation

### Prerequisites

  - **Python:** 3.10 or later
  - **LaTeX Distribution:** (Optional, for compiling the paper)

### Python Setup

```bash
# Clone the repository
git clone <repository-url>
cd Ethic-Latex

# Install dependencies
pip install -r requirements.txt
```

### LaTeX Setup

To compile the research paper:

```bash
# Using the provided script (Mac/Linux)
bash scripts/compile_latex.sh

# Or manually
pdflatex ethical_riemann_hypothesis.tex
bibtex ethical_riemann_hypothesis
pdflatex ethical_riemann_hypothesis.tex
```

-----

## 🚀 Quick Start

### Running a Basic Simulation

```python
from simulation.core import generate_world, BiasedJudge, evaluate_judgement
from simulation.core import select_ethical_primes, compute_Pi_and_error
from simulation.visualization import plot_Pi_B_E

# 1. Generate moral action space
actions = generate_world(num_actions=1000, complexity_dist='zipf')

# 2. Create and apply a judgment system
judge = BiasedJudge(bias_strength=0.2, noise_scale=0.1)
evaluate_judgement(actions, judge, tau=0.3)

# 3. Extract ethical primes (critical errors)
primes = select_ethical_primes(actions, importance_quantile=0.9)

# 4. Compute and plot error distribution
Pi_x, B_x, E_x, x_vals = compute_Pi_and_error(primes, X_max=100)
plot_Pi_B_E(x_vals, Pi_x, B_x, E_x)
```

### Running Jupyter Notebooks

```bash
bash scripts/start_jupyter.sh
```

Start with `simulation/notebooks/01_basic_simulation.ipynb` for an introduction.

-----

## ☁️ Cloud Deployment

  - **🚀 Streamlit Cloud (Recommended - 5 minutes):** Push to GitHub, then deploy via the Streamlit website.
  - **📓 Binder (For Notebooks - 2 minutes):** Deploy your notebooks for live access.
  - **🐳 Docker (Any Platform):**

<!-- end list -->

```bash
docker build -t erh-app .
docker run -p 8501:8501 erh-app streamlit run simulation/app.py
```

See `docs/CLOUD_DEPLOYMENT.md` for detailed guides.

-----

## 🔒 ERH-on-Security PoC Design Document

**Subject: Analysis of Structural Misjudgment in GitLab DevSecOps Pipelines**

This design document outlines a Proof of Concept (PoC) applying the ERH framework to quantify how systematic and fatal security misjudgments accumulate as project complexity increases within a DevSecOps pipeline.

### 1\. Objectives & Scope

| Category | Description |
| :--- | :--- |
| **Core Problem** | Quantify the rate at which "truly fatal security misjudgments" (structural misjudgments) accumulate as the complexity of project changes grows. |
| **Hypothesis** | Can we use an ERH-style metric to quantify this **Structural Risk Growth**? |
| **Scope** | GitLab Merge Request security review pipeline (using SAST/DAST results and post-merge incident data as proxies for ground truth). |

### 2\. Mapping ERH to Security Context

| ERH Concept | Security Context Mapping |
| :--- | :--- |
| **Action ($a$)** | Defined as a **security decision event** for a single **Merge Request (MR)**. |
| **Complexity ($c(a)$)** | A composite metric of MR size and scope: $c(a) = \text{norm}(\log(1 + \text{lines\_changed}) + \lambda \cdot \text{files\_changed} + \dots)$ |
| **True Value ($V(a)$)** | **Ground Truth.** $+1$: Safe merge (no post-merge incident/unresolved high issue). $-1$: Unsafe merge (resulted in incident or high-severity issue). |
| **Judgment System ($J(a)$)** | **Pipeline Judge ($J_{\text{pipe}}$):** Automated CI/SAST results. **Human Judge ($J_{\text{human}}$):** Reviewer behavior/override. **Combined Judge ($J_{\text{combo}}$).** |
| **Error ($\Delta(a)$)** | $\Delta(a) = J(a) - V(a)$. |
| **Ethical Prime ($P$)** | A **Critical Misjudgment** ($M(a)=1$) on a **High-Importance** asset ($w(a)$ in top quantile). |

### 3\. Data Schema Design

#### actions (Core: MR Decisions)

| Column | Type | Description |
| :--- | :--- | :--- |
| `action_id` | PK (MR ID) | Unique identifier for the decision event |
| `lines_added` | int | Complexity factor |
| `files_changed` | int | Complexity factor |
| `services_touched`| string[] | Subsystems affected (via path mapping) |
| `merged_at` | timestamp | Time of merge (nullable) |

#### ground\_truth

| Column | Type | Description |
| :--- | :--- | :--- |
| `action_id` | FK | Link to MR |
| `V` | float [-1, 1] | **True Value** (Post-merge security impact) |
| `has_post\_incident`| bool | Flag for incident discovery within observation window |
| `unresolved\_high`| bool | True if merged with unmitigated high/critical issues |

#### derived\_metrics (Calculated on-the-fly or materialized)

| Column | Type | Description |
| :--- | :--- | :--- |
| `action_id` | FK | Link to MR |
| `c` | float | Normalized **Complexity** |
| `delta` | float | $\Delta(a)$ **Error** |
| `is_prime` | bool | Flag indicating an **Ethical Prime** |

### 4\. ERH Analysis Flow and Metrics

1.  **Preprocessing:** Ingest GitLab API data (MRs, security reports) and calculate $c(a)$, $V(a)$, $w(a)$, $J(a)$, and prime marking for all actions.
2.  **ERH-style Metrics:** Compute the following for each judge:

| Metric | Formula | Description |
| :--- | :--- | :--- |
| **Mistake Rate (MR)** | $\frac{1}{N} \sum M(a)$ | Overall misjudgment frequency. |
| **Prime Count $\Pi(x)$** | Count of primes where $c(a) \leq x$. | Cumulative critical error count by complexity. |
| **Error Growth $\alpha$** | Fit $|E(x)| \sim C \cdot x^\alpha$ | Log-log linear regression to find the exponent $\alpha$. |

3.  **Interpretation:** Check if $\alpha$ satisfies the ERH-style boundary. $\alpha \approx 0.5$ implies **Riemann-healthy** system with controlled risk growth. $\alpha \geq 1$ implies systematic degradation.

-----

## 📈 Key Results (Expected)

The following table is a placeholder to be filled with simulation results.

| Judge Type | Exponent $\alpha$ | ERH Satisfied? | Growth Rate Interpretation |
| :--- | :--- | :--- | :--- |
| **Biased** | TBD | TBD | -- |
| **Noisy** | TBD | TBD | -- |
| **Conservative**| TBD | TBD | Low risk, potentially high friction ($\alpha < 0.5$) |
| **Radical** | TBD | TBD | High risk accumulation, systematic failure ($\alpha \geq 1.0$) |

-----

## 📚 Documentation and Future Work

  - **Simulation Framework:** See `simulation/README.md`
  - **Installation Guide:** See `docs/INSTALL.md`
  - **Theory:** See `ethical_riemann_hypothesis.tex`

### Applications to AI Ethics

The ERH framework provides:

1.  **Quantitative Criterion**: AI systems should satisfy $|E(x)| = O(\sqrt{x})$.
2.  **Bias Detection**: Violations of ERH indicate systematic failures.
3.  **Fairness Analysis**: Ethical primes highlight critical errors on vulnerable groups.

### Future Work

  - Apply the framework to real-world AI systems (e.g., content moderation).
  - Develop theoretical proofs for ERH boundary conditions.
  - Explore connections to causal inference and quantum computing implementations.

-----

## © Citation and License

### Citation

If you use this framework in your research, please cite:

```bibtex
@article{ethical_riemann_hypothesis,
  title={The Ethical Riemann Hypothesis: A Mathematical Framework for Analyzing Moral Judgment Errors},
  author={[Author Name]},
  journal={[To be completed]},
  year={2025}
}
```

### License

This project is licensed under the **MIT License**.

### Contributing

Contributions, suggestions, and discussions are welcome.

**Contact:** admin@dennisleehappy.org

```
```