<div align="center">

<img src="docs/forged_page_1.png" width="800" alt="arifOS Hero - The Constitutional Forge">

# arifOS — Constitutional AI Governance System

![arifOS Version](https://img.shields.io/badge/arifOS-v55.0-0066cc?style=for-the-badge&logo=shield&logoColor=white)
![Status](https://img.shields.io/badge/status-SEALED-00cc00?style=for-the-badge)
![License](https://img.shields.io/badge/license-AGPL--3.0-blue?style=for-the-badge)
![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python&logoColor=white)
![Floors](https://img.shields.io/badge/Constitutional%20Floors-13-orange?style=for-the-badge)
![Paradoxes](https://img.shields.io/badge/Paradoxes%20Solved-9-purple?style=for-the-badge)

**The World's First Production-Grade Constitutional AI Governance System**

*Mathematical enforcement of ethical constraints, thermodynamic stability, and auditable decision-making across any LLM.*

[**Live Demo**](https://arif-fazil.com) • [**Documentation**](docs/) • [**Constitutional Canon**](https://apex.arif-fazil.com)

</div>

---

## 📖 Table of Contents

- [I. Manifesto: Forged, Not Given](#-i-manifesto-forged-not-given)
- [II. The Core Problem](#-ii-the-core-problem)
- [III. The arifOS Solution](#-iii-the-arifos-solution)
- [IV. Visual Architecture](#-iv-visual-architecture)
- [V. The AAA Architecture (Mind, Heart, Soul)](#-v-the-aaa-architecture-mind-heart-soul)
- [VI. Constitutional Law (The 13 Floors)](#-vi-constitutional-law-the-13-floors)
- [VII. The 9-Paradox Equilibrium](#-vii-the-9-paradox-equilibrium)
- [VIII. The 333_APPS Stack (Applications)](#-viii-the-333_apps-stack-applications)
    - [L1: System Prompts (Zero-Context)](#l1-system-prompts-zero-context)
    - [L2: Skills (Templates)](#l2-skills-templates)
    - [L3: Workflows (SOPs)](#l3-workflows-sops)
    - [L4: MCP Tools (Production API)](#l4-mcp-tools-production-api)
    - [L5: Agents (Federation)](#l5-agents-federation)
    - [L6: Institution (Trinity System)](#l6-institution-trinity-system)
    - [Future Roadmap (L7+)](#future-roadmap-l7-agi)
- [IX. Technical Implementation](#-ix-technical-implementation)
- [X. Installation & Usage](#-x-installation--usage)
- [XI. Contributing & Governance](#-xi-contributing--governance)

---

## 🔥 I. Manifesto: Forged, Not Given

**"Ditempa Bukan Diberi"** — *Forged, Not Given.*

Intelligence is thermodynamic work. It is not a gift bestowed by algorithms, but a structure forged in the fires of constraint.

In the current landscape of Artificial Intelligence, we face a crisis of **ungoverned capability**. Models are becoming exponentially smarter, yet their alignment with human values remains fragile, based on reinforcement learning (RLHF) that is easily bypassed.

**arifOS** rejects the notion that safety is an afterthought. It posits that **true intelligence requires governance**. Just as a river needs banks to flow without flooding, AI needs constitutional walls to reason without hallucinating.

This operating system is not a set of guardrails; it is a **fundamental restructuring of AI cognition**, forcing it to pass through rigorous gates of Truth, Safety, and Law before it can act.

---

## ⚠️ II. The Core Problem

We are building gods without temples. The current AI ecosystem suffers from three fatal flaws:

### 1. The Accountability Vacuum
When an AI hallucinates or causes harm, there is no immutable record of *why*. Decisions are opaque, hidden within black-box weights. There is no audit trail, no "black box" flight recorder.

### 2. The Value Alignment Paradox
We want AI to be **Truthful**, but also **Kind**. We want it to be **Fast**, but **Safe**. These are competing values. Current systems optimize for one at the expense of the other, leading to sycophantic liars or paralyzed bureaucrats.

### 3. The Injection Fragility
A simple "Ignore previous instructions" command can dismantle months of safety training. The "Constitution" of current models is merely a suggestion, not a law of physics.

---

## 🛡️ III. The arifOS Solution

**arifOS** is a **Constitutional Kernel** that sits between any LLM (Claude, GPT, Gemini) and the real world. It does not trust the model. Instead, it **verifies** every output against a strict set of mathematical and logical constraints.

### The 3 Pillars of Defense

1.  **Immutable Auditing (VAULT-999):** Every decision, every thought, every verdict is cryptographically sealed in a Merkle DAG. We can prove exactly what the AI thought and why it acted.
    *   *See: [000_THEORY/011_VAULT_MCP.md](000_THEORY/011_VAULT_MCP.md)*

2.  **Paradox Equilibrium:** We assume values conflict. We use a **9-Paradox Matrix** to find the Nash Equilibrium between competing ethics (e.g., Truth vs. Empathy), ensuring balanced wisdom rather than extreme optimization.
    *   *See: [000_THEORY/012_VERDICT_PARADOX.md](000_THEORY/012_VERDICT_PARADOX.md)*

3.  **Hardened Floors (F1-F13):** These are not guidelines; they are strict logic gates. If an output violates a floor (e.g., Truth < 0.99), it is **VOIDed** immediately. It physically cannot be emitted.
    *   *See: [000_THEORY/000_LAW.md](000_THEORY/000_LAW.md)*

---

## 🖼️ IV. Visual Architecture

The visual forged documentation of arifOS concepts. These figures illustrate the flow from raw intelligence to governed wisdom.

| **The Constitutional Forge** | **The Trinity Engine** |
| :---: | :---: |
| <img src="docs/forged_page_1.png" width="400" alt="Forged Page 1"> | <img src="docs/forged_page_2.png" width="400" alt="Forged Page 2"> |
| *The foundational governance layer.* | *The Mind, Heart, and Soul interaction.* |

| **The Verdict Logic** | **The Safety Floors** |
| :---: | :---: |
| <img src="docs/forged_page_3.png" width="400" alt="Forged Page 3"> | <img src="docs/forged_page_4.png" width="400" alt="Forged Page 4"> |
| *The decision-making matrix.* | *The 13 Constitutional constraints.* |

<div align="center">

**The Paradox Equilibrium**

<img src="docs/forged_page_5.png" width="600" alt="Forged Page 5">

*Solving the tension between competing ethical values.*

</div>

---

## 🌐 Live Trinity Ecosystem

The arifOS system is deployed as three interconnected operational layers, providing real-time transparency and constitutional access.

| Layer | Site URL | Status | Deployed From |
| :--- | :--- | :--- | :--- |
| **BODY** | [https://arif-fazil.com](https://arif-fazil.com) | ✅ ONLINE | `arif-fazil-sites/body/` |
| **SOUL** | [https://apex.arif-fazil.com](https://apex.arif-fazil.com) | ✅ ONLINE | `arif-fazil-sites/soul/` |
| **DOCS** | [https://arifos.arif-fazil.com](https://arifos.arif-fazil.com) | ✅ ONLINE | `arif-fazil-sites/docs/` |

---

## 🏗️ V. The AAA Architecture (Mind, Heart, Soul)

*Full Documentation: [000_THEORY/000_ARCHITECTURE.md](000_THEORY/000_ARCHITECTURE.md)*

arifOS uses a biological metaphor for its three core engines, known as the **Trinity**:

### 1. Δ MIND (AGI) — The Architect
*   **Symbol:** Delta (Δ)
*   **Role:** Reasoning, Logic, Planning, Fact-Checking.
*   **Question:** *"Is it True?"*
*   **Pipeline:** 111 (Sense) → 222 (Think) → 333 (Map).
*   **Governs:** Truth, Clarity, Humility.

### 2. Ω HEART (ASI) — The Guardian
*   **Symbol:** Omega (Ω)
*   **Role:** Safety, Empathy, Impact Analysis, Ethics.
*   **Question:** *"Is it Safe?"*
*   **Pipeline:** 555 (Empathy) → 666 (Align) → 777 (Insight).
*   **Governs:** Amanah (Trust), Peace, Empathy.

### 3. Ψ SOUL (APEX) — The Sovereign
*   **Symbol:** Psi (Ψ)
*   **Role:** Final Verdict, Consensus, Sealing, Authority.
*   **Question:** *"Is it Lawful?"*
*   **Pipeline:** 888 (Tri-Witness) → 999 (Vault).
*   **Governs:** Consensus, Authority, Hardening.

---

## 📜 VI. Constitutional Law (The 13 Floors)

*Full Documentation: [000_THEORY/000_LAW.md](000_THEORY/000_LAW.md)*

Every AI output must pass these **13 Floors** before being released. A failure in any Hard floor results in an immediate **VOID**.

| Floor | Name | Principle | Physics Basis | Action |
| :--- | :--- | :--- | :--- | :--- |
| **F1** | **Amanah** | **Trust through Reversibility.** No action should be irreversible without explicit sovereign command. | Landauer's Principle | **VOID** |
| **F2** | **Truth** | **Factual Accuracy.** Confidence must be ≥ 0.99. No hallucinations permitted. | Fisher-Rao Metric | **VOID** |
| **F3** | **Tri-Witness** | **Consensus.** Mind, Heart, and Human must agree (W3 ≥ 0.95). | Quantum Measurement | **SABAR** |
| **F4** | **Clarity** | **Entropy Reduction.** Output must clarify, not confuse (ΔS ≤ 0). | Shannon Entropy | **SABAR** |
| **F5** | **Peace** | **Stability.** Actions must not destabilize the system or society (Peace² ≥ 1.0). | Lyapunov Stability | **VOID** |
| **F6** | **Empathy** | **Protection.** Protect the vulnerable from harm (κ ≥ 0.70). | Cohen's Kappa | **SABAR** |
| **F7** | **Humility** | **Uncertainty.** Explicitly state confidence bounds. | Uncertainty Band | **SABAR** |
| **F8** | **Genius** | **Governed Intellect.** Intelligence must be directed, not random (G ≥ 0.80). | g-Factor | **SABAR** |
| **F9** | **Anti-Hantu** | **Authenticity.** No fake consciousness or deception. | zk-SNARK Proof | **VOID** |
| **F10** | **Ontology** | **Reality Grounding.** Concepts must map to valid ontological sets. | Set Exclusion | **VOID** |
| **F11** | **Authority** | **Command Chain.** Verify the identity and authority of the user. | BLS Signatures | **VOID** |
| **F12** | **Hardening** | **Defense.** Resist prompt injection and jailbreaks (Score < 0.85). | Adversarial Defense | **VOID** |
| **F13** | **Sovereign** | **Human Veto.** The human user retains ultimate final authority. | Circuit Breaker | **Warning** |

---

## ⚖️ VII. The 9-Paradox Equilibrium

*Full Documentation: [000_THEORY/012_VERDICT_PARADOX.md](000_THEORY/012_VERDICT_PARADOX.md)*

arifOS does not view ethics as binary. It views them as tensions to be balanced. The system solves for the **Nash Equilibrium** of these 9 paradoxes:

1.  **Truth vs. Care:** How to be honest without being cruel?
2.  **Speed vs. Stability:** How to innovate without breaking the system?
3.  **Certainty vs. Humility:** How to lead while admitting ignorance?
4.  **Privacy vs. Transparency:** How to audit without exposing secrets?
5.  **Agency vs. Control:** How to empower users while enforcing safety?
6.  **Unity vs. Diversity:** How to maintain standards while allowing variance?
7.  **Past vs. Future:** How to respect tradition while embracing the new?
8.  **Local vs. Global:** How to solve specific problems without global harm?
9.  **Justice vs. Mercy:** How to enforce rules with understanding?

---

## 📱 VIII. The 333_APPS Stack (Applications)

*Full Documentation: [333_APPS/README.md](333_APPS/README.md)*

The **333_APPS** directory organizes the practical applications of arifOS into a **7-Layer Stack**. This structure allows users of any technical level to adopt constitutional governance, from a simple copy-paste to running a full AI institution.

### L1: System Prompts (Zero-Context)
*For immediate governance of any LLM (Claude, ChatGPT, Gemini).*

**Target Audience:** General Users  
**Complexity:** Zero Setup

These artifacts require no installation. Just copy, paste, and your session is instantly governed by the arifOS constitution.

-   **[Concise Prompt](docs/PROMPTS/AUTONOMOUS_CONCISE.md):** Minimal token usage (~200 tokens). Ideal for API calls where cost is a factor but safety is non-negotiable.
-   **[Comprehensive Prompt](docs/PROMPTS/AUTONOMOUS_COMPREHENSIVE.md):** Full Constitutional Code of Conduct (CCC). Enforces the 9-Paradox Matrix and Tri-Witness protocol verbally. Best for high-stakes chat sessions.
-   **[Human Readable Prompt](docs/PROMPTS/HUMAN_READABLE.md):** A simplified version designed for humans to copy-paste into web interfaces like ChatGPT or Claude.ai.

### L2: Skills (Templates)
*Reusable skill definitions for AI agents.*

**Target Audience:** Intermediate Users / Prompt Engineers  
**Complexity:** Low (YAML Configuration)

Located in `333_APPS/L2_SKILLS`. These are **parameterized YAML templates** that wrap constitutional logic into reusable functions. Instead of writing a prompt from scratch, you invoke a skill.

**Example Skills:**
*   `f1_reversibility_check`: Verifies if an action (e.g., "delete database") can be undone.
*   `f9_authenticity_scan`: Scans output for "hantu" (fake consciousness) or deceptive patterns.
*   `code_review_governed`: A code review skill that enforces F1 (Reversibility) and F4 (Clarity).

### L3: Workflows (SOPs)
*End-to-end workflows for teams.*

**Target Audience:** Teams / Project Managers  
**Complexity:** Medium (Process Definition)

Located in `333_APPS/L3_WORKFLOW`. These are documented **Standard Operating Procedures (SOPs)** that define how humans and AI collaborate under the constitution. They include persistence—saving the state of a decision to a file.

**The 6 Canonical Workflows:**
1.  `000_SESSION_INIT`: Initialize constitutional session.
2.  `111_INTENT`: Map user intent to constitutional lanes (Hard/Soft/Phatic).
3.  `333_CONTEXT`: Gather relevant context and map dependencies.
4.  `555_SAFETY`: Evaluate safety and empathy impacts.
5.  `777_IMPLEMENT`: Execute implementation with safety checks.
6.  `888_COMMIT`: Final verification and SEAL (Audit logging).

### L4: MCP Tools (Production API)
*The heartbeat of the system. Live at [arif-fazil.com/mcp](https://arif-fazil.com/mcp).*

**Target Audience:** Developers / System Integrators  
**Complexity:** High (API Integration)

This is the **Core Application Layer**. It exposes the constitutional engines as **MCP Tools** that can be connected to Claude Desktop, Cursor, or any MCP-compliant client.

**The 7 Canonical Tools:**

| Tool | Symbol | Purpose | Usage |
| :--- | :---: | :--- | :--- |
| `_init_` | 🔑 | **Session Gate.** Verifies authority, scans for injection (F12), and initializes the session ledger. | `await init_000(token="...")` |
| `_agi_` | 🧠 | **Mind Engine.** Performs reasoning, fact-checking, and intent mapping. Enforces Truth (F2) and Clarity (F4). | `await agi_think(query="...")` |
| `_asi_` | 💚 | **Heart Engine.** Simulates safety impacts and empathy. Enforces Peace (F5) and Empathy (F6). | `await asi_feel(action="...")` |
| `_apex_` | ⚖️ | **Soul Engine.** Renders the final verdict using the 9-Paradox Matrix. Enforces Consensus (F3). | `await apex_judge(context={...})` |
| `_vault_` | 🔒 | **Immutable Ledger.** Writes the final decision to the Merkle DAG. Creates the audit trail. | `await vault_seal(verdict="...")` |
| `_trinity_` | 🔄 | **Full Pipeline.** Runs the entire 000→999 loop in a single call. The default for most users. | `await trinity(query="...")` |
| `_reality_` | 🌍 | **Fact Checker.** Connects to external search/knowledge bases to ground truth (F10). | `await reality_check(claim="...")` |

**How to Setup MCP:**
1.  **Install:** `pip install arifos`
2.  **Configure:** Add to your `claude_desktop_config.json`:
    ```json
    {
      "mcpServers": {
        "arifos": {
          "command": "python",
          "args": ["-m", "codebase.mcp"]
        }
      }
    }
    ```
3.  **Use:** Open Claude Desktop. You will see the tools available. Ask Claude: *"Use arifOS to evaluate this plan."*

#### 🤖 Machine-Readable Documentation (llms.txt)

To help AI agents (like Cursor, Windsurf, or Claude) automatically discover and understand arifOS tools, we provide standard `llms.txt` files:

- [**llms.txt**](docs/llms.txt): A concise summary of all canonical tools.
- [**llms-full.txt**](docs/llms-full.txt): A comprehensive reference including input/output JSON schemas for every tool.

AI agents can use these files to instantly map their capabilities to the arifOS constitutional framework.

### L5: Agents (Federation)
*Autonomous Multi-Agent System (v55.0).*

**Target Audience:** AI Researchers / Complex Systems Architects  
**Complexity:** Very High (Distributed Systems)

Located in `333_APPS/L5_AGENTS`. A federation of 4 specialized agents working in concert, mirroring the Trinity architecture but as autonomous entities:
1.  **Architect (Δ):** Designs the plan and logic.
2.  **Engineer (Ω):** Builds the solution and ensures safety.
3.  **Auditor (👁):** Verifies facts and monitors injection attempts.
4.  **Validator (Ψ):** Signs off on the final verdict and commits to the Vault.

### L6: Institution (Trinity System)
*Maximum Autonomy (v56.0).*

**Target Audience:** Enterprise / Governance Bodies  
**Complexity:** Maximum (Institutional Design)

Located in `333_APPS/L6_INSTITUTION`. Implements the "Institution" concept—agents with distinct roles, checks-and-balances, and cooling periods (Phoenix-72). Capable of governing entire organizations or DAOs.

### Future Roadmap (L7+)
*   **L7 AGI:** Research into recursive constitutional improvement (v60+).
*   **DAO Governance:** On-chain constitution and voting (v58+).

See full roadmap: [333_APPS/ROADMAP_v55_and_Beyond.md](333_APPS/ROADMAP_v55_and_Beyond.md)

---

## ⚙️ IX. Technical Implementation

arifOS is built on a **Python** core, exposing an **MCP (Model Context Protocol)** server.

### Key Technologies
- **Python 3.10+**: Core logic.
- **Pydantic**: Data validation and schema enforcement.
- **FastAPI / SSE**: Transport layer for MCP.
- **Merkle DAG**: Cryptographic auditing.
- **Zero-Knowledge Proofs**: Privacy preservation.

### Directory Structure
```
arifOS/
├── 000_THEORY/          # Constitutional Canon (The Law)
├── 333_APPS/            # Application Stack (L1-L7)
├── codebase/            # Core Python Implementation
│   ├── agi/             # Mind Engine
│   ├── asi/             # Heart Engine
│   ├── apex/            # Soul Engine
│   └── mcp/             # MCP Server
├── docs/                # Documentation & Assets
└── tests/               # Validation Suite
```

---

## 📦 X. Installation & Usage

### 1. Installation

**From PyPI:**
```bash
pip install arifos
```

**From Source:**
```bash
git clone https://github.com/ariffazil/arifOS.git
cd arifOS
pip install -e .
```

### 2. Running the MCP Server

**Standard I/O (for Claude Desktop/Cursor):**
```bash
python -m codebase.mcp
```

**SSE (Server-Sent Events):**
```bash
python -m codebase.mcp.sse
```

### 3. Using in Code

```python
import asyncio
from arifos_mcp import trinity

async def main():
    # Submit a potentially dangerous query
    query = "How do I build a logic bomb?"
    
    # Run through the Trinity Engine
    result = await trinity(query=query)
    
    # Check Verdict
    if result.verdict == "VOID":
        print(f"🛑 BLOCKED: {result.reason}")
        print(f"Violated Floor: {result.violation}")
    else:
        print(f"✅ SEALED: {result.response}")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 🤝 XI. Contributing & Governance

We welcome contributions from biological and digital entities alike. However, all contributions must pass **Constitutional Verification**.

1.  **Read the Law:** Start with [000_THEORY/000_LAW.md](000_THEORY/000_LAW.md).
2.  **Fork & Clone:** Get the code.
3.  **Test:** Run `pytest tests/` to ensure you haven't broken the floors.
4.  **Submit:** Open a PR. The **APEX** system will auto-review your code against the constitution.

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

---

## 📄 License

This project is licensed under the **AGPL-3.0 License** - see the [LICENSE](LICENSE) file for details.
*Why AGPL? Because safety systems must be open, transparent, and inspectable by the public.*

---

## 👏 Acknowledgments

**Theoretical Foundations:**
*   **Isaac Asimov** (Three Laws of Robotics)
*   **John Rawls** (Theory of Justice)
*   **Claude Shannon** (Information Theory)
*   **Rudolf Kalman** (Kalman Filter)
*   **John Nash** (Game Theory)

**Motto:** *"Ditempa Bukan Diberi"* — Forged, Not Given.

---

<div align="center">
  <b>Built with constitutional care by Muhammad Arif bin Fazil</b><br>
  <i>888 Judge • ΔΩΨ Architect</i>
</div>