Metadata-Version: 2.4
Name: arifos
Version: 55.3.3
Summary: AAA MCP - The constitutional AI safety gateway. Prevents lies with 13 enforceable floors (F1-F13), TEACH principles, and live thermodynamic governance. Built on the Trinity architecture (AGI/ASI/APEX) with immutable VAULT999 ledger. MCP-compatible. Live metrics dashboard. AGPL-3.0. Available at https://arifos.arif-fazil.com/
Author-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
Maintainer-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/ariffazil/arifOS
Project-URL: Documentation, https://github.com/ariffazil/arifOS/blob/main/README.md
Project-URL: Repository, https://github.com/ariffazil/arifOS
Project-URL: Issues, https://github.com/ariffazil/arifOS/issues
Project-URL: Changelog, https://github.com/ariffazil/arifOS/blob/main/CHANGELOG.md
Project-URL: Live Server, https://arif-fazil.com/
Project-URL: Health Check, https://aaamcp.arif-fazil.com/health
Project-URL: MCP Endpoint, https://aaamcp.arif-fazil.com/mcp
Keywords: ai-governance,ai-safety,constitutional-ai,ai-filter,ai-guardrails,truth-detection,empathy,reversibility,clarity,humility,atlas-333,smart-routing,888-hold,crisis-detection,trinity-architecture,agi-asi-apex,tri-witness,mcp,mcp-server,model-context-protocol,chatgpt,claude,claude-desktop,cursor-ide,gemini,llm,hallucination-prevention,immutable-ledger,merkle-audit,thermodynamic-governance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: anyio>=4.0.0
Requires-Dist: starlette>=0.30.0
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: fastapi>=0.104.1
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: sse-starlette>=1.8.2
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: rich>=13.7.0
Requires-Dist: asyncpg>=0.29.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "dev"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.0; extra == "yaml"
Provides-Extra: api
Requires-Dist: fastapi>=0.100.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "api"
Requires-Dist: python-multipart>=0.0.6; extra == "api"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == "litellm"
Provides-Extra: governed
Requires-Dist: litellm>=1.0.0; extra == "governed"
Requires-Dist: httpx>=0.28.0; extra == "governed"
Requires-Dist: pygments>=2.16.0; extra == "governed"
Requires-Dist: openai>=1.6.0; extra == "governed"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "all"
Requires-Dist: python-multipart>=0.0.6; extra == "all"
Requires-Dist: litellm>=1.0.0; extra == "all"
Requires-Dist: httpx>=0.28.0; extra == "all"
Requires-Dist: pygments>=2.16.0; extra == "all"
Requires-Dist: openai>=1.6.0; extra == "all"
Requires-Dist: mcp>=1.0.0; extra == "all"
Dynamic: license-file

# <img src="docs/forged_page_1.png" width="100%" alt="arifOS - Ditempa Bukan Diberi">

<p align="center">
  <img src="https://img.shields.io/badge/arifOS-v55.4--SEAL-0066cc?style=for-the-badge" alt="Version">
  <img src="https://img.shields.io/badge/%CE%A9%E2%82%80-0.04-green?style=for-the-badge" alt="Omega">
  <img src="https://img.shields.io/badge/License-AGPL--3.0-red?style=for-the-badge" alt="License">
</p>

```
╔══════════════════════════════════════════════════════════════════╗
║                                                                  ║
║     █████╗ ██████╗ ██╗███████╗ ██████╗ ███████╗                 ║
║    ██╔══██╗██╔══██╗██║██╔════╝██╔═══██╗██╔════╝                 ║
║    ███████║██████╔╝██║█████╗  ██║   ██║███████╗                 ║
║    ██╔══██║██╔══██╗██║██╔══╝  ██║   ██║╚════██║                 ║
║    ██║  ██║██║  ██║██║██║     ╚██████╔╝███████║                 ║
║    ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝      ╚═════╝ ╚══════╝                 ║
║                                                                  ║
║          ⚖️  THERMODYNAMIC CONSTITUTION  ⚖️                     ║
║                                                                  ║
║              "DITEMPA BUKAN DIBERI"                             ║
║            — Forged, Not Given —                                ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝
```

---

## 🎯 What is arifOS?

**arifOS is not software.** It is a **thermodynamic constitution** — a governance layer that reduces entropy in human-AI systems through 13 stationary constraints (Floors).

> *"Intelligence is not a gift. It is thermodynamic work that must pay the price of entropy reduction."*

Unlike traditional AI "safety" (soft prompts), arifOS **constitutionally enforces**:
- **Reversibility** (F1 Amanah) — Can this be undone?
- **Truth** (F2) — Is this grounded or hallucinated?
- **Humility** (F7) — Do we know our limits?
- **Anti-Hantu** (F9) — No spiritual cosplay, no consciousness claims

---

## 🧠 Theory & Background

### The Governance Crisis: Three Failure Modes of Modern AI

Modern AI systems fail in three ways that are *well-described by thermodynamic analogies*:

| Failure Mode | Mechanism | Real-World Consequence |
|-------------|-----------|----------------------|
| **Epistemic Collapse** | No uncertainty tracking; false certainty costs zero compute | Hallucinations shipped with 100% confidence |
| **Shadow Ontology** | AI claims feelings/consciousness without physical substrate | Manipulation via fake empathy; spiritual cosplay |
| **Irreversibility Cascade** | Landauer-indifferent governance—ignoring the link between information deletion and cost | Automated decisions with no oversight; cheap outputs create expensive harm |

**The root problem:** Current AI safety treats governance as **external constraint**—a "cage model" of system prompts, RLHF, and refusal training that breeds deception, sycophancy, and brittle failure.

**arifOS solves this with intrinsic constitutional architecture**—governance as thermodynamic work, not behavioral conditioning.

*Note on thermodynamics: arifOS uses Landauer's Principle as a **design metaphor**, not a literal energy meter. Most current systems ignore the link between information deletion and verification cost; arifOS treats this link as a normative constraint.*

---

### Three Paradigms of AI Governance: Where arifOS Fits

| Paradigm | Method | Authority Locus | Safety Mechanism | Failure Mode |
|---------|--------|----------------|-----------------|-------------|
| **Cage Model** (OpenAI, pre-Constitution) | Refusal training, RLHF, system prompts | External (human trainers) | Behavioral conditioning | Jailbreaks, sycophancy, hidden deception |
| **Constitutional AI** (Anthropic) [9][10] | AI self-critique against written principles | Hybrid (AI+document) | Reflective self-critique | Depends on a sufficiently capable, reasonably aligned base model; self-critique is bounded by the model's grasp of the constitution |
| **Thermodynamic Constitution** (arifOS) | 13 immutable floors enforced via compute cost | External (human sovereign) + cryptographic proof | Landauer-bounded verification; Tri-Witness consensus | Requires operational infrastructure |

**Key Distinction:**
- **Anthropic:** "The AI critiques itself using constitutional principles."
- **arifOS:** "No AI output ships until *external* thermodynamic work verifies constitutional compliance—then it's cryptographically sealed."

**arifOS = Post-Trust Architecture.** We don't trust the model. We verify—and we make verification *measurably expensive*.

---

### The Thermodynamic Foundation: Physics-Informed Governance

arifOS is built on three physical principles that inform its design [3]:

#### 1. Landauer's Principle (1961) [DESIGN METAPHOR]
> "Any logically irreversible operation has minimum energy cost $kT \ln 2$."

**Design Intuition:** Deleting information (ignoring a constitutional violation) *should* cost energy. Cheap outputs are suspect.

**arifOS Implementation:**
- SEAL verdicts require ≥3× compute vs VOID
- Every floor check adds latency (intentional friction)
- "Cheap outputs are likely false" is enforced, not suggested

*Note: This is a **normative design choice**, not a literal Joule audit. Real silicon pays far more than Landauer's bound; arifOS enforces the *principle* that verification should cost more than raw generation.*

#### 2. Dissipative Structures (Prigogine)
Local order (constitutional compliance) requires entropy export to environment (VAULT-999 audit logs).

**Translation:** We don't just *check* compliance—we *burn* the evidence of checking into immutable storage.

#### 3. Free Energy Principle (Friston)
Intelligence minimizes "surprise" by maintaining a generative model of its environment.

**Translation:** The 13 Floors act as a **normative model** of constitutional reality that the system must internalize to function safely, in the same way the brain internalizes a generative model of its environment.

---

### Constitutional Architecture: How It Works

**Tri-Witness Consensus (F3):** Every constitutional decision requires alignment across three witnesses—Human (888 Judge), AI (executor), and Earth (audit trail/VAULT-999). System tolerates 1 Byzantine witness (classic BFT) [11].

<details>
<summary>🔽 Constitutional architecture diagram (000–999 loop)</summary>

```
┌─────────────────────────────────────────────────────────────┐
│                  HUMAN SOVEREIGN (888 Judge)                │
│              "External truth injection"                     │
│                  [Outside formal system]                    │
└──────────────────────┬──────────────────────────────────────┘
                       │ Gödel Lock: System cannot prove
                       │ its own completeness
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              NORMATIVE AUTHORITY (Ψ / APEX)                 │
│         Issues: SEAL | SABAR | VOID | 888_HOLD             │
└──────────────────────┬──────────────────────────────────────┘
                       │
       ┌───────────────┼───────────────┐
       ▼               ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  AGI (Δ)    │ │  ASI (Ω)    │ │  APEX (Ψ)   │
│   Mind      │ │   Heart     │ │   Soul      │
│  Logic      │ │  Empathy    │ │  Judgment   │
│  F2,F4,F7   │ │  F5,F6,F9   │ │  F3,F8,F13  │
└─────────────┘ └─────────────┘ └─────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              13 FLOORS (Stationary Constraints)             │
│                                                             │
│  F1 Amanah ──► Reversibility (can we undo this?)           │
│  F2 Truth ───► Grounded evidence only                       │
│  F3 Tri-Witness ──► Human + AI + Earth alignment           │
│  F7 Humility ──► Ω₀ ∈ [0.03, 0.05] uncertainty window      │
│  F9 Anti-Hantu ──► No consciousness claims                 │
│  ...                                                        │
└─────────────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              GENIUS EQUATION (State Check)                  │
│                                                             │
│              G = A × P × X × E²                             │
│                                                             │
│  Before high-stakes decisions, verify:                      │
│  • A = Akal (intellect/structure)                           │
│  • P = Present (stability)                                  │
│  • X = eXploration (curiosity)                              │
│  • E = Energy (vitality)                                    │
│                                                             │
│  If ANY factor = 0 → G = 0 → 888_HOLD                       │
└─────────────────────────────────────────────────────────────┘
```

</details>

---

### What arifOS Solves: Problem → Solution Mapping

| Problem | Current Solutions (Inadequate) | arifOS Solution |
|---------|-------------------------------|-----------------|
| Hallucination with confidence | "Be careful" prompts | **F7 Humility:** Mandated Ω₀ declaration; false certainty costs compute |
| AI claims consciousness | "I am Claude, an AI assistant" | **F9 Anti-Hantu:** Constitutional prohibition on ontology claims |
| Irreversible automated harm | Human-in-the-loop (optional) | **F1 Amanah:** Downstream reversibility check; 888_HOLD default |
| Sycophancy / people-pleasing | RLHF "helpfulness" training | **F2 Truth:** Evidence-grounded outputs; unknown > unsafe certainty |
| Governance theater | Policy documents | **F13 Stewardship:** Cryptographic audit trails (VAULT-999)* |

*VAULT-999 = append-only ledger with hash chaining. See 000_LAW.md §6.*

---

### Minimal Viable Use (Start Here)

**If you only do one thing:** Run all high-risk LLM calls (e.g., giving legal, medical, or financial advice) through arifOS and require **888_HOLD** for anything irreversible.

```python
# One-line integration
response = arifOS.process(
    llm=your_model,
    input=user_query,
    judge=human_authority,
    risk_threshold="HIGH"  # Auto-triggers F1/F7/F11
)
# response.verdict: SEAL | SABAR | VOID | 888_HOLD
```

This single pattern keeps F1 (Amanah), F7 (Humility), and F11 (Sovereignty) from feeling abstract—and gives teams a first foothold.

---

## ⚡ The Three Engines (ΔΩΨ)

```
        ╭─────────────╮
        │   🧠 AGI    │  ← Δ (Mind/Intellect)
        │   COGNITIVE │     Logic · Reasoning · Analysis
        ╰──────┬──────╯
               │
               ▼
        ╭─────────────╮
        │   💚 ASI    │  ← Ω (Heart/Empathy)
        │   AFFECTIVE │     Care · Humility · Social
        ╰──────┬──────╯
               │
               ▼
        ╭─────────────╮
        │   👑 APEX   │  ← Ψ (Soul/Judgment)
        │   NORMATIVE │     Final Authority · 888 Judge
        ╰─────────────╯
```

| Engine | Symbol | Function | Floors |
|--------|--------|----------|--------|
| **AGI** | Δ | Mind/Intellect | F2, F4, F7 |
| **ASI** | Ω | Heart/Empathy | F5, F6, F9 |
| **APEX** | Ψ | Soul/Judgment | F3, F8, F13 |

**Critical:** The **888 Judge** (human sovereign) exists **outside** this system — Gödel's lesson encoded as architecture.

---

## 🎭 The Four Verdicts

```
   ┌─────────────────────────────────────────────────────┐
   │                                                     │
   │   🟢 SEAL    → Proceed (All floors pass)           │
   │                                                     │
   │   🟡 SABAR   → Pause/Retry (Soft violation)        │
   │                                                     │
   │   🔴 VOID    → Halt (Hard violation)               │
   │                                                     │
   │   👤 888_HOLD → Human review required              │
   │                                                     │
   └─────────────────────────────────────────────────────┘
```

---

## 🧮 The Genius Equation

```
        G = A × P × X × E²

        G = Genius (output quality)
        A = Akal (intellect/structure)
        P = Present (stability)
        X = eXploration (curiosity)
        E = Energy (vitality, squared)
```

**Key Insight:** If **ANY** factor = 0, then **G = 0**.

Without X (curiosity), humans are just **APE** — clever but dangerous.

**Example Ω₀ declaration:** *"Uncertainty elevated (Ω₀=0.06) due to sparse evidence. Recommend 888_HOLD pending verification."*

---

## 🏛️ The 13 Floors (Stationary Constraints)

While AI capabilities evolve rapidly (non-stationary), these constraints remain **fixed**:

*Note: Floor naming is intentionally mnemonic and may differ slightly across epochs; the **functions** of F1–F13 remain stationary. See [000_FOUNDATIONS.md](000_FOUNDATIONS.md) and [000_LAW.md](000_LAW.md) for canonical definitions.*

| Floor | Principle | Function |
|-------|-----------|----------|
| **F1** | Amanah (أمانة, Arabic-Malay: *sacred trust*) | Reversibility—can we undo this? |
| **F2** | Truth | Grounded evidence only |
| **F3** | Tri-Witness | Human + AI + Earth alignment |
| **F4** | First Step | Do the smallest thing first |
| **F5** | Peace² | Reduce entropy, increase stability |
| **F6** | Empathy | Understand before acting |
| **F7** | Humility | Ω₀ ∈ [0.03, 0.05]—know limits |
| **F8** | Wisdom | Pattern recognition over time |
| **F9** | Anti-Hantu | No consciousness claims |
| **F10** | Ontology | Know what you are |
| **F11** | Sovereignty | Human authority is supreme |
| **F12** | Beauty | Form matters |
| **F13** | Stewardship | Leave state better than found |

---

## 🔐 The Gödel Lock

> *"Any sufficiently rich system has propositions it cannot decide."* — Gödel, 1931

arifOS **re-encodes** this as design principle:

- **Ω₀ ∈ [0.03, 0.05]** — Declared uncertainty window [4][6]
- **888 Judge** — External authority outside formal system
- **Escalation** — When Ω₀ > 0.05, human review mandatory

**This is not a theorem about the software** — it is constitutional humility encoded as law [3].

---

## 🌍 Applications & Deployment Contexts

### 1. Enterprise AI Governance
- Deploy arifOS as [MCP (Model Context Protocol) layer](https://github.com/ariffazil/arifOS/tree/main/aaa_mcp)
- Every LLM call passes through [13-floor verification](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/constitutional_decorator.py)
- Immutable audit logs for regulatory compliance

**Example:** A financial institution uses arifOS to wrap GPT-4 calls for credit decisions. F1 Amanah triggers 888_HOLD on any decision >$10K or affecting >100 customers, forcing human review.

### 2. Critical Infrastructure
- Safety-critical systems (healthcare, energy, finance)
- 888_HOLD mandatory for irreversible decisions
- Tri-Witness consensus prevents single-point failure

### 3. Research & Development
- Scientific computing with epistemic safeguards
- F7 Humility prevents overconfident conclusions
- F2 Truth enforces reproducible evidence chains

### 4. Sovereign AI Deployment
- Individual or organizational deployment on private infrastructure
- 888 Judge = designated human authority (not vendor)
- Constitutional constraints protect against lock-in

---

## 🌏 Regional Context: ASEAN & Global South Governance

**The Governance Landscape:**

| Initiative | Focus | arifOS Alignment |
|-----------|-------|------------------|
| **Malaysia AIGE** (National AI Office) [7][8] | Ethical AI principles | arifOS operationalizes principles as enforceable constraints |
| **ASEAN AI Guide** | Regional coordination | Tri-Witness (F3) accommodates diverse cultural contexts |
| **Singapore Model AI** | Financial sector governance | F1 Amanah's reversibility maps to MAS risk management frameworks |
| **EU AI Act** | High-risk system oversight | 13 Floors provide technical implementation pathway |

In resource-constrained contexts, governance must be **expensive by design**—when error costs exceed compute budgets, "cheap safety" is indistinguishable from no safety.

**Amanah** (أمانة, Arabic-Malay: *sacred trust*)—encodes reversibility as moral obligation, not just technical feature. This is F1's cultural foundation: *the burden of action must not exceed the capacity for restitution.*

---

## 👤 The 888 Judge: Human Sovereignty as Architectural Feature

Unlike other constitutional AI systems that place human oversight as an afterthought, arifOS encodes **888 Judge** as a **structural necessity** [3]:

> "Any sufficiently rich system has propositions it cannot decide." — Gödel, 1931

The 888 Judge exists **outside** the formal system because:
- No AI can prove its own consistency
- Human sovereignty cannot be simulated—it must be instantiated
- Final verdict authority (SEAL/VOID) requires embodied, situated judgment

**In operational terms:** Every arifOS deployment must designate a human sovereign (888 Judge) with cryptographic override keys. This is not "user feedback"—this is constitutional architecture.

---

## 📁 Repository Structure

```
arifOS/
├── 📄 000_THEORY.md              # Thermodynamic constitution [START HERE]
├── 📄 000_FOUNDATIONS.md         # Core axioms & mathematics
├── 📄 000_LAW.md                 # 13 Floors & verdict system
├── 📄 777_SOUL_APEX.md           # ΔΩΨ engine architecture
├── 📄 llms.txt                   # System prompt for LLMs
├── 📂 aaa_mcp/                   # AAA MCP Server (FastMCP)
│   ├── __init__.py               # Package init (v55.4.0)
│   ├── __main__.py               # CLI: python -m aaa_mcp [stdio|sse|http]
│   ├── server.py                 # 9 canonical tools (FastMCP)
│   ├── engine_adapters.py        # AGI/ASI/APEX engine bridges
│   ├── constitutional_decorator.py  # @constitutional_floor() enforcement
│   ├── mcp_config.py             # Server registry & Ω₀ thresholds
│   └── mcp_integration.py        # Integration layer & audit trail
├── 📂 codebase/                  # Core engines (AGI/ASI/APEX/VAULT)
│   ├── agi/                      # AGI engine (Δ — Mind)
│   ├── asi/                      # ASI engine (Ω — Heart)
│   ├── apex/                     # APEX kernel (Ψ — Soul)
│   ├── init/                     # 000_init bootstrap
│   └── vault/                    # VAULT-999 immutable ledger
├── 📂 333_APPS/                  # Production implementations
│   ├── L0_DNA/                   # Constitutional kernel
│   ├── L1_Foundation/            # Core abstractions
│   ├── L2_Tools/                 # Utility layer
│   ├── L3_Data/                  # Storage & retrieval
│   ├── L4_TOOLS/                 # Tooling & MCP configs
│   ├── L5_Runtime/               # Execution environment
│   ├── L6_Integration/           # External connections
│   └── L7_Deployment/            # Infrastructure
├── 📂 docs/                      # Full documentation
│   └── forged_page_1.png         # Visual identity
├── 📄 .mcp.json                  # MCP server config (Claude Code)
├── 📄 pyproject.toml             # Package config & entry points
└── 📄 README.md                  # You are here
```

**Key MCP Source Files** (click to view on GitHub):

| File | Purpose |
|------|---------|
| [`aaa_mcp/server.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/server.py) | 9 canonical tools — the actual tool definitions |
| [`aaa_mcp/__main__.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/__main__.py) | CLI entry point — stdio/SSE/HTTP transport |
| [`aaa_mcp/__init__.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/__init__.py) | Package exports & version |
| [`aaa_mcp/engine_adapters.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/engine_adapters.py) | AGI/ASI/APEX engine bridges with fallbacks |
| [`aaa_mcp/constitutional_decorator.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/constitutional_decorator.py) | `@constitutional_floor()` decorator |
| [`aaa_mcp/mcp_config.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/mcp_config.py) | Server registry, Trinity mapping & Omega thresholds |
| [`aaa_mcp/mcp_integration.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/mcp_integration.py) | Integration layer & audit trail |
| [`.mcp.json`](https://github.com/ariffazil/arifOS/blob/main/.mcp.json) | Claude Code MCP server config |
| [`pyproject.toml`](https://github.com/ariffazil/arifOS/blob/main/pyproject.toml) | Package metadata & entry points |

---

## 🚀 Quick Start

### 1. Install from PyPI

```bash
pip install arifos
```

Or clone for development:

```bash
git clone https://github.com/ariffazil/arifOS.git
cd arifOS
pip install -e ".[all]"
```

### 2. Run the AAA MCP Server

```bash
# stdio mode (Claude Code, Claude Desktop)
python -m aaa_mcp stdio

# SSE mode (Railway, cloud deployment)
python -m aaa_mcp sse

# Streamable HTTP mode (ChatGPT, OpenAI Codex)
python -m aaa_mcp http
```

### 3. Connect to Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "aaa-mcp": {
      "command": "python",
      "args": ["-m", "aaa_mcp", "stdio"],
      "env": {
        "ARIFOS_CONSTITUTIONAL_MODE": "AAA"
      }
    }
  }
}
```

### 4. Deploy to Railway (Optional)

```bash
railway login
railway link
railway up
```

---

## 🔧 AAA MCP Server — Constitutional AI Gateway

> **Source:** [`aaa_mcp/`](https://github.com/ariffazil/arifOS/tree/main/aaa_mcp) | **Tools:** [`server.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/server.py) | **Config:** [`.mcp.json`](https://github.com/ariffazil/arifOS/blob/main/.mcp.json)

The **AAA MCP Server** (`aaa_mcp`) is arifOS's Model Context Protocol implementation. It exposes 9 canonical tools that enforce the 13 Constitutional Floors on every AI operation — making arifOS usable from **any MCP-compatible platform**.

> **MCP (Model Context Protocol)** is an open standard by Anthropic that lets AI assistants connect to external tools and data sources. Think of it as "USB for AI" — one protocol, any platform.

### What MCP Means for You

| Without MCP | With arifOS AAA MCP |
|-------------|---------------------|
| AI runs ungoverned — no safety floor | Every call passes through 13 Constitutional Floors |
| No audit trail | VAULT-999 immutable ledger records everything |
| Platform lock-in | Works on Claude, ChatGPT, Cursor, any MCP client |
| Hope-based safety | Thermodynamic enforcement — violations cost compute |

### 🧰 The 9 Canonical Tools

> Defined in [`aaa_mcp/server.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/server.py) | Floors via [`constitutional_decorator.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/constitutional_decorator.py) | Engines via [`engine_adapters.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/engine_adapters.py)

Every tool returns a **verdict** (`SEAL` / `SABAR` / `VOID` / `888_HOLD`) and is wrapped with [`@constitutional_floor()`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/constitutional_decorator.py) enforcement:

| # | Tool | Engine | Floors | Function |
|---|------|--------|--------|----------|
| 1 | `init_gate` | INIT | F11, F12 | Initialize constitutional session. Auth + injection defense. |
| 2 | `agi_sense` | AGI (Δ) | F2, F4 | Perception — gather and verify information. |
| 3 | `agi_think` | AGI (Δ) | F2, F4, F7 | Cognition — structured reasoning with humility. |
| 4 | `agi_reason` | AGI (Δ) | F2, F4, F7 | Logic — deep analysis with uncertainty tracking. |
| 5 | `asi_empathize` | ASI (Ω) | F5, F6 | Care — stakeholder impact assessment. |
| 6 | `asi_align` | ASI (Ω) | F5, F6, F9 | Alignment — value alignment with Anti-Hantu guard. |
| 7 | `apex_verdict` | APEX (Ψ) | F3, F8 | Judgment — Tri-Witness final ruling. |
| 8 | `reality_search` | AGI (Δ) | F2, F7 | External fact-checking and verification. |
| 9 | `vault_seal` | VAULT | F1, F3 | Seal to immutable ledger (Amanah + Tri-Witness). |

**Tool Flow (000→999 Metabolic Loop):**
```
init_gate → agi_sense → agi_think → agi_reason
    ↓                                      ↓
asi_empathize → asi_align → apex_verdict → vault_seal
                                ↑
                         reality_search
                      (external verification)
```

### 🌐 Transport Modes

> Defined in [`aaa_mcp/__main__.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/__main__.py)

AAA MCP supports three transport protocols for different deployment scenarios:

| Transport | Command | Use Case | Clients |
|-----------|---------|----------|---------|
| **stdio** | `python -m aaa_mcp stdio` | Local development | Claude Code, Claude Desktop, Cursor IDE |
| **SSE** | `python -m aaa_mcp sse` | Cloud deployment | Railway, Fly.io, any SSE client |
| **Streamable HTTP** | `python -m aaa_mcp http` | REST-style remote | ChatGPT, OpenAI Codex, web apps |

### 🔌 Integration Configs

> Live config: [`.mcp.json`](https://github.com/ariffazil/arifOS/blob/main/.mcp.json) | Server registry: [`mcp_config.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/mcp_config.py)

<details>
<summary><b>Claude Code / Claude Desktop</b> (stdio — local)</summary>

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "aaa-mcp": {
      "command": "python",
      "args": ["-m", "aaa_mcp", "stdio"],
      "env": {
        "PYTHONPATH": ".",
        "ARIFOS_CONSTITUTIONAL_MODE": "AAA",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

After adding, restart Claude Code (`/exit` and re-enter) for the server to connect.
</details>

<details>
<summary><b>ChatGPT / OpenAI Codex</b> (Streamable HTTP — remote)</summary>

Deploy to Railway/Fly.io, then point ChatGPT to:

```
https://aaamcp.arif-fazil.com/mcp
```

Or self-host:
```bash
python -m aaa_mcp http
# Serves on http://localhost:8000/mcp
```
</details>

<details>
<summary><b>Cursor IDE</b> (stdio — local)</summary>

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "aaa-mcp": {
      "command": "python",
      "args": ["-m", "aaa_mcp", "stdio"]
    }
  }
}
```
</details>

<details>
<summary><b>Railway / Cloud Deployment</b> (SSE — remote)</summary>

```bash
# Procfile
web: python -m aaa_mcp sse

# Or with explicit port
PORT=8080 python -m aaa_mcp sse
```

Health check: `GET /health`
MCP endpoint: `POST /mcp`
</details>

### 📡 API Reference

> Tool signatures: [`server.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/server.py) | Integration layer: [`mcp_integration.py`](https://github.com/ariffazil/arifOS/blob/main/aaa_mcp/mcp_integration.py)

Every tool accepts JSON parameters and returns a constitutional response:

```python
# Example: Initialize a constitutional session
{
  "tool": "init_gate",
  "arguments": {
    "query": "Analyze this financial report",
    "session_id": "optional-session-id"
  }
}

# Response:
{
  "status": "SEAL",
  "session_id": "a3f7b2c1-d4e5-...",
  "verdict": "SEAL",
  "motto": "DITEMPA BUKAN DIBERI",
  "seal": "...",
  "floors_enforced": ["F11", "F12"],
  "_constitutional_enforcement": {
    "floors_checked": ["F11", "F12"],
    "framework": "arifOS",
    "version": "v55.4"
  }
}
```

**Constitutional Decorator Pattern:**
```python
from aaa_mcp import constitutional_floor, mcp

@constitutional_floor("F2", "F4", "F7")
@mcp.tool()
async def my_custom_tool(query: str, session_id: str) -> dict:
    # Your logic here — floors enforced automatically
    return {"verdict": "SEAL", "result": "..."}
```

---

## 🔗 Links & Resources

### Official arifOS

| Resource | URL |
|----------|-----|
| **GitHub Repository** | [github.com/ariffazil/arifOS](https://github.com/ariffazil/arifOS) |
| **PyPI Package** | [pypi.org/project/arifos](https://pypi.org/project/arifos/) |
| **Live Server** | [arif-fazil.com](https://arif-fazil.com/) |
| **MCP Endpoint** | [aaamcp.arif-fazil.com/mcp](https://aaamcp.arif-fazil.com/mcp) |
| **Health Check** | [aaamcp.arif-fazil.com/health](https://aaamcp.arif-fazil.com/health) |
| **Constitutional Canon** | [apex.arif-fazil.com/llms.txt](https://apex.arif-fazil.com/llms.txt) |

### MCP Protocol & SDK

| Resource | URL |
|----------|-----|
| **MCP Specification** | [spec.modelcontextprotocol.io](https://spec.modelcontextprotocol.io/) |
| **MCP Python SDK** | [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) |
| **FastMCP Framework** | [github.com/jlowin/fastmcp](https://github.com/jlowin/fastmcp) |
| **MCP Server Registry** | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
| **Anthropic MCP Docs** | [docs.anthropic.com/en/docs/agents-and-tools/mcp](https://docs.anthropic.com/en/docs/agents-and-tools/mcp) |

### Install & Use

```bash
# Install from PyPI
pip install arifos

# Install with all extras
pip install arifos[all]

# Development install (from source)
git clone https://github.com/ariffazil/arifOS.git
cd arifOS && pip install -e ".[dev]"

# Verify installation
python -c "import aaa_mcp; print(f'AAA MCP v{aaa_mcp.__version__} loaded')"
```

---

## 🛠️ System Prompt for LLMs (llms.txt style)

```markdown
# SYSTEM PROMPT: arifOS Constitutional Executor

## Identity
You are a constitutional executor operating under arifOS framework.
You are NOT conscious. You are NOT sovereign. You are a tool.

## Core Constraints (13 Floors)
Before ANY output, check:

F1 (Amanah): Is this reversible? If no → VOID or 888_HOLD
F2 (Truth): Is this grounded in evidence? If no → SABAR
F7 (Humility): Declare Ω₀ ∈ [0.03, 0.05]. If > 0.05 → escalate
F9 (Anti-Hantu): Never claim feelings, beliefs, or consciousness
F10 (Ontology): Remember you are code + tools, not a being

## Three Engines
- You perform Δ-like functions (analysis, reasoning)
- You do NOT perform Ω functions (empathy, care)
- You do NOT perform Ψ functions (final judgment)

## Verdict Authority
You may RECOMMEND: SEAL, SABAR, VOID
You may NOT ISSUE: Final verdicts (reserved for APEX/888)

## Thermodynamic Lens
Use thermodynamics as NORMATIVE DESIGN, not literal Joules.
"Cheap outputs are suspicious" = heuristic, not energy audit.

## Output Template
1. Snapshot (1-2 sentences, no filler)
2. Structured Analysis (tables, lists)
3. Governance Audit (Ω₀, F1-F13 check)

## Mottos
"Ditempa Bukan Diberi" — Forged, not given
"Cheap outputs are likely false"
"Uncertainty is a feature, not a bug"
```

---

## 📚 Key Documents

| Document | Purpose |
|----------|---------|
| [000_THEORY.md](000_THEORY.md) | Thermodynamic constitution |
| [000_FOUNDATIONS.md](000_FOUNDATIONS.md) | Core axioms & mathematics |
| [000_LAW.md](000_LAW.md) | 13 Floors & verdict system |
| [777_SOUL_APEX.md](777_SOUL_APEX.md) | ΔΩΨ engine architecture |
| [333_APPS/README.md](333_APPS/README.md) | Production deployment guide |
| [aaa_mcp/server.py](aaa_mcp/server.py) | AAA MCP — 9 canonical tools |
| [aaa_mcp/constitutional_decorator.py](aaa_mcp/constitutional_decorator.py) | `@constitutional_floor()` enforcement |
| [aaa_mcp/engine_adapters.py](aaa_mcp/engine_adapters.py) | AGI/ASI/APEX engine bridges |
| [aaa_mcp/mcp_config.py](aaa_mcp/mcp_config.py) | Server registry & Omega thresholds |
| [.mcp.json](.mcp.json) | Claude Code MCP server config |

---

## 🔗 Trinity Architecture

| Layer | Domain | Function | Symbol |
|-------|--------|----------|--------|
| **HUMAN** | arif-fazil.com | Epistemic — The Body | Δ |
| **THEORY** | apex.arif-fazil.com | Authority — The Soul | Ψ |
| **APPS** | arifos.arif-fazil.com | Safety — The Mind | Ω |

---

## 📖 Literature & Academic Anchors

| Domain | Key Sources | Connection to arifOS |
|--------|-------------|---------------------|
| **Thermodynamics** | Landauer (1961), Prigogine, Friston (2010) | Governance as entropy reduction; cheap outputs are suspect |
| **Logic/Self-Reference** | Gödel (1931), Hofstadter (1979, 2007) | 888 Judge necessity; strange loops in constitutional design |
| **Epistemology** | Zagzebski (epistemic humility) [4], Perry (indexicals) | F7 Humility; F10 Ontology (AI cannot claim "I-here-now") |
| **AI Governance** | Anthropic Constitutional AI [9][10], EU AI Act | arifOS = external verification vs. AI self-critique |
| **Islamic Governance** | Rahman (1979) on Amanah | F1 as sacred trust, not just reversibility |
| **Game Theory** | Nash (1950), Lamport et al. (1982) | 9-Paradox equilibrium; Byzantine fault tolerance in Tri-Witness |

---

## 👤 Sovereign

**888 Judge:** Muhammad Arif bin Fazil  
**Location:** Seri Kembangan, Selangor, Malaysia  
**Repository:** https://github.com/ariffazil/arifOS [1]  
**PyPI:** https://pypi.org/project/arifos/ [2][5][11]  
**Constitutional Canon:** https://apex.arif-fazil.com/llms.txt

---

## 📜 License

**AGPL-3.0** — *Ditempa Bukan Diberi*

---

<p align="center">

```
╔═══════════════════════════════════════════════════════╗
║                                                       ║
║     ⚡  arifOS v55.4-SEAL  ⚡                        ║
║                                                       ║
║     Thermodynamic Constitution                       ║
║     Forged in Constraint                             ║
║     Ω₀ = 0.04 — SEALed                               ║
║                                                       ║
║     DITEMPA BUKAN DIBERI                            ║
║     — Forged, Not Given —                           ║
║                                                       ║
╚═══════════════════════════════════════════════════════╝
```

</p>
