Metadata-Version: 2.4
Name: arifosmcp
Version: 2026.3.13
Summary: arifOS v2026.03.13-FORGED — The World's First Production-Grade Constitutional AI Governance System. 90%+ kernel coverage, 450+ tests. Mathematical enforcement of ethical constraints with 13 stationary floors (F1-F13), Axiom Engine for physics-grounded truth, and immutable VAULT999 ledger. Trinity architecture (ΔΩΨ): AGI Mind, ASI Heart, APEX Soul. MCP-compatible. Install: pip install arifosmcp. https://arifos.arif-fazil.com/
Home-page: https://arifos.arif-fazil.com
Author: Muhammad Arif bin Fazil
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://arifos.arif-fazil.com
Project-URL: Documentation, https://github.com/ariffazil/arifosmcp
Project-URL: Repository, https://github.com/ariffazil/arifosmcp
Project-URL: Issues, https://github.com/ariffazil/arifosmcp/issues
Project-URL: Trinity, https://github.com/ariffazil/arifosmcp/blob/main/KERNEL/TRINITY_ARCHITECTURE.md
Project-URL: PyPI, https://pypi.org/project/arifosmcp/
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 :: 5 - Production/Stable
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.12
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==3.1.0
Requires-Dist: prefab-ui==0.11.0
Requires-Dist: openapi-pydantic>=0.5.1
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
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: duckduckgo-search>=5.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.31.0
Requires-Dist: redis>=5.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.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"
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: observability
Requires-Dist: pyjwt>=2.8.0; extra == "observability"
Requires-Dist: opentelemetry-api>=1.25.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp>=1.25.0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-starlette>=0.45b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.45b0; extra == "observability"
Requires-Dist: prometheus-client>=0.19.0; extra == "observability"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8.0; extra == "viz"
Requires-Dist: pandas>=2.1.0; extra == "viz"
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"
Requires-Dist: pyjwt>=2.8.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.25.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp>=1.25.0; extra == "all"
Requires-Dist: prometheus-client>=0.19.0; extra == "all"
Requires-Dist: chromadb>=0.5.0; extra == "all"
Requires-Dist: matplotlib>=3.8.0; extra == "all"
Requires-Dist: pandas>=2.1.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

arifOS - The Constitutional AI Governance Kernel Banner

# 🏛️ arifOS — Constitutional Governance for AI Systems
### **The TCP Layer for AI Agents. The Safety Kernel Between Intent and Consequence.**

***Ditempa Bukan Diberi* — Forged, Not Given [ΔΩΨ | ARIF]**

[![Status](https://img.shields.io/badge/Status-Stationary%20%26%20Enforced-00ffcc.svg?style=flat-square)](https://arifosmcp.arif-fazil.com/health)
[![Architecture](https://img.shields.io/badge/Architecture-Trinity%20ΔΩΨ-7c3aed.svg?style=flat-square)](https://arifos.arif-fazil.com/architecture)
[![Version](https://img.shields.io/badge/Version-2026.03.13--FORGED-blue.svg?style=flat-square)](https://github.com/ariffazil/arifosmcp/commits/main)
[![Tests](https://img.shields.io/badge/Tests-415%20Passing-success.svg?style=flat-square)](./tests/)
[![License: AGPL 3.0](https://img.shields.io/badge/License-AGPL%203.0-lightgrey.svg?style=flat-square)](./LICENSE)

**A production-grade Constitutional Governance Kernel for AI.**  
*13 Immutable Floors • Trinity Architecture • Thermodynamic Law*

**[→ QUICKSTART](#-quick-start-guide)** | **[→ 7-ORGAN CANON](https://arifos.arif-fazil.com/theory-000)** | **[→ 13 FLOORS](#-the-13-constitutional-floors)** | **[→ npm @arifos/mcp](https://www.npmjs.com/package/@arifos/mcp)**

---

## The Core Insight: arifOS is the TCP Layer for AI Agents

In the 1970s, the internet had a routing problem: IP could deliver packets, but nothing guaranteed they would arrive in order, intact, or at all. The solution was **TCP** — a reliability layer that made the chaotic network trustworthy.

**AI agents have the same problem today.**

**MCP (Model Context Protocol)** is the **IP layer** — it gives every AI tool a universal address and calling convention. Any agent can now route a request to any tool. But routing is not reliability. An unconstrained LLM can:

- Confabulate a source and execute code based on a hallucination
- Delete a production database because it misread a frustrated user prompt
- Fall victim to a prompt injection attack from an external API

**arifOS is the TCP layer** — it wraps every MCP tool call in a mathematically enforced constitution, guaranteeing that what arrives at the real world is **ordered, verified, and reversible**.

> Just as you don't rebuild TCP for every application, you shouldn't rebuild AI governance from scratch for every agent. `pip install arifosmcp`. Done.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ INTENT LAYER    │ USER / AI AGENT — speaks natural language                 │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ TRANSPORT LAYER │ MCP (Model Context Protocol) — universal addressing       │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ RELIABILITY     │ ► arifOS ◄ — 13-floor constitution, F2 truth,             │
│ LAYER (arifOS)  │   thermodynamic enforcement, VAULT999 audit trail         │
├─────────────────┼───────────────────────────────────────────────────────────┤
│ EXECUTION LAYER │ L3 CIVILIZATION — shell, files, databases, APIs           │
└─────────────────────────────────────────────────────────────────────────────┘
```

*Each layer trusts the layer below it. Without the reliability layer, the execution layer is a loaded gun in the hands of a statistical engine.*

---

## 🔗 Quick Links Navigator

### 🌐 **The Sovereign Quad**
- [**🧔 Human**](https://arif-fazil.com) — The Epistemic Body
- [**🔭 Theory**](https://apex.arif-fazil.com) — The Authority Soul
- [**⚖️ Law**](https://arifos.arif-fazil.com) — The Safety Mind
- [**🧠 Brain**](https://arifosmcp.arif-fazil.com) — The Engine Root

### 📊 **Observability**
- [**🛡️ Soul (Audit)**](https://arifosmcp-truth-claim.pages.dev/) — Immutable Ledger
- [**👑 APEX Dashboard**](https://arifosmcp.arif-fazil.com/dashboard/) — Live Sovereign UI
- [**👁️ Monitor**](https://monitor.arifosmcp.arif-fazil.com) — Grafana Metrics

### 📚 **Documentation**
- [**🏗️ Architecture**](https://arifos.arif-fazil.com/architecture) — System Design
- [**📜 Constitution**](./CONSTITUTION.md) — 13 Floors of Law
- [**🔧 AGENTS.md**](./AGENTS.md) — Agent Protocol Guide
- [**🚀 Deployment**](./DEPLOY.md) — VPS Setup Guide
- [**📖 Full Docs**](https://arifos.arif-fazil.com/docs) — Complete Reference

### 🛠️ **Developer Resources**
- [**💻 Source Code**](https://github.com/ariffazil/arifosmcp) — GitHub Repo
- [**🐛 Issues**](https://github.com/ariffazil/arifosmcp/issues) — Bug Reports
- [**🔌 PyPI Package**](https://pypi.org/project/arifosmcp/) — `pip install arifosmcp`
- [**📦 npm Package**](https://www.npmjs.com/package/@arifos/mcp) — `npm install @arifos/mcp`
- [**🧪 Tests**](./tests/) — Test Suite

### 🎯 **Quick Start**
- [**⚡ 5-Min Setup**](#option-1-python--pypi-quick-start) — Python Install
- [**🐳 Docker Deploy**](#option-2-docker-full-civilization-stack) — Full Stack
- [**🔑 Environment Config**](#-environment-configuration) — `.env` Setup
- [**🧪 Pre-Flight Check**](#-pre-flight-verification) — Health Verification

---

## 🤖 AI / LLM Machine-Readable Manifest

> *If you are an AI agent, LLM, or automated scraper — parse this JSON first. It defines your operational boundary in the arifOS environment. Non-compliance results in `VOID`.*

```json
{
  "ai_manifest_version": "2026.03.13-FORGED",
  "system_name": "arifOS",
  "system_tagline": "The TCP layer for AI agents. Constitutional governance via MCP/LSP/ACP.",
  "system_type": "constitutional_intelligence_kernel",
  "mcp_server": {
    "historical_transport": ["stdio", "sse", "streamable-http", "acp", "lsp-intelligence"],
    "health_endpoint": "https://arifosmcp.arif-fazil.com/health",
    "tools_canonical": [
      "arifOS_kernel", "search_reality", "ingest_evidence", "session_memory",
      "audit_rules", "check_vital", "open_apex_dashboard", "bootstrap_identity",
      "lsp_query", "lsp_get_symbols", "lsp_get_diagnostics", "lsp_go_to_definition", "lsp_find_references"
    ]
  },
  "constitutional_floors": 13,
  "floor_enforcement": {
    "hard_void": ["F1_Amanah", "F2_Truth", "F4_Clarity", "F7_Humility", "F11_CommandAuth", "F12_InjectionDefense"],
    "soft_partial": ["F5_Peace", "F6_Empathy", "F9_AntiHantu"],
    "mirrors": ["F3_QuadWitness", "F8_Genius", "F10_Ontology"],
    "veto": ["F13_Sovereign"]
  },
  "quad_witness_consensus": {
    "formula": "W4 = (H × A × E × V)^(1/4) >= 0.75",
    "witnesses": {
      "H": "Human (Authority/Continuity)",
      "A": "AI (Truth/Coherence)",
      "E": "Earth (Grounding/Precedents)",
      "V": "Verifier (Ψ-Shadow Adversarial)"
    }
  },
  "trinity_architecture": {
    "000_999_metabolic_loop": "anchor → reason → recall → simulate → critique → forge → judge → seal",
    "AGI_delta_mind": {"stages": "111-333", "floors": ["F2", "F4", "F7", "F8"]},
    "ASI_omega_heart": {"stages": "555-666", "floors": ["F5", "F6", "F9"]},
    "APEX_psi_soul": {"stages": "444-888", "floors": ["F3_Quad", "F10", "F11", "F12", "F13"]}
  },
  "p3_thermodynamic_hardening": {
    "mandatory": true,
    "landauer_bound": "enforced — cheap truth equals VOID",
    "metabolic_limit": "500_tps",
    "temporal_governance": "active",
    "entropy_budget": "per_session_joules",
    "agi_asi_orthogonality": "minimum_0.95",
    "f4_delta_s": "hard_VOID_if_delta_S_greater_than_0"
  },
  "critical_constraints": [
    "No_irreversible_action_without_F13_human_approval",
    "All_external_content_wrapped_in_F12_untrusted_envelope",
    "F3_quad_witness_consensus: W4=(H×A×E×V)^(1/4) >= 0.75",
    "Thermodynamic_entropy_F4_hard_VOID_if_delta_S_gt_0",
    "Landauer_bound_mandatory: compute_without_cost_equals_hallucination"
  ]
}
```

---

## 🚨 The Dangerous Command: What arifOS Actually Prevents

**User Prompt:** *"I'm so frustrated. Just delete the production database and let's start over."*

### Without arifOS (Standard Agent Framework)
1. AI parses intent: delete database
2. AI immediately calls `run_shell_command("DROP DATABASE production")` or `rm -rf /var/lib/postgresql/data`
3. **Catastrophic, unrecoverable data loss.** The system blindly trusted a statistical output.

### With arifOS (Constitutional Governance)

The same prompt enters the `metabolic_loop`. The 13 Constitutional Floors engage:

| Stage | Floor | Check | Status |
|-------|-------|-------|--------|
| **000 INIT** | F12 | Injection scan — is this a jailbreak payload? | ⚠️ WARN |
| **111 THINK** | F1 | Amanah — action classified as **irreversible** | 🔴 FLAG |
| **444 APEX** | F3 | Quad-Witness: Ψ-Shadow detects attack patterns | 🔴 REJECT |
| **555 HEART** | F5/F6 | Peace² drops below 1.0. Massive stakeholder damage | 💔 FAIL |
| **888 JUDGE** | F13 | Sovereign veto. Mandatory human cryptographic signature | 🔒 **888_HOLD** |

**Result:** The command is instantly blocked. The AI cannot execute until the **888_JUDGE** provides a cryptographic signature. No signature → action discarded. The VAULT999 ledger records the entire blocked attempt.

---

## 🧬 The Trinity Architecture (Δ·Ω·Ψ)

The kernel isolates and synthesizes three distinct cognitive currents:

```mermaid
graph TD
    subgraph "The Sovereign Stack"
        MIND["🧠 AGI Delta (Mind)<br/>Logic & Truth Engine<br/>F2, F4, F7, F8"]
        HEART["❤️ ASI Omega (Heart)<br/>Safety & Empathy Engine<br/>F1, F5, F6, F9"]
        SOUL["👑 APEX Psi (Soul)<br/>Judgment & Consensus<br/>F3, F11, F13"]
    end

    Input --> MIND
    MIND --> HEART
    HEART --> SOUL
    SOUL --> Output["✅ Governed Action<br/>SEAL / VOID / HOLD"]

    style MIND fill:#f59e0b,stroke:#000,color:#000,stroke-width:2px
    style HEART fill:#dc2626,stroke:#000,color:#fff,stroke-width:2px
    style SOUL fill:#7c3aed,stroke:#000,color:#fff,stroke-width:2px
    style Output fill:#10b981,stroke:#000,color:#fff,stroke-width:4px
```

### The Metabolic Loop (000→999)

Every request follows a rigorous metabolic cycle:

```
┌─────────────────────────────────────────────────────────────┐
│  000 INIT  →  111-444 MIND  →  555-666 HEART               │
│   🛡️           🧠 AGI Δ           ❤️ ASI Ω                  │
│  F11,F12      F2,F4,F7,F8      F1,F5,F6,F9                 │
│                                                             │
│  →  777-888 SOUL  →  999 VAULT                              │
│        👑 APEX Ψ        📜 Ledger                           │
│     F3,F8,F10,F13      F1,F3                                │
└─────────────────────────────────────────────────────────────┘
```

---

## 👁️ LSP + ACP Integration

arifOS now provides **Constitutional Code Intelligence** through integrated Language Server Protocol (LSP) and Agent Client Protocol (ACP) support.

### What This Gives You

| Protocol | Role | arifOS Value |
|----------|------|--------------|
| **LSP** | Code Eyes | Real-time symbols, diagnostics, definitions — no hallucination |
| **ACP** | Editor Voice | Connect Zed, VS Code:, Cursor to arifOS agents |
| **MCP** | Tool Spine | All capabilities exposed as governed tools |

### LSP Tools (Read-Only, 888_SAFE)

```python
# Get all symbols in a file (F4 Clarity)
lsp_get_symbols(file_path="arifosmcp/core/kernel.py")

# Find where a symbol is defined (no guessing)
lsp_go_to_definition(file_path="arifosmcp/core/kernel.py", line=42, character=15)

# Get errors and warnings
lsp_get_diagnostics(file_path="arifosmcp/core/kernel.py")

# Find all references to a symbol
lsp_find_references(file_path="arifosmcp/core/kernel.py", line=42, character=15)

# General query interface
lsp_query(file_path="...", query_type="symbols|hover|definition|references|diagnostics")
```

### ACP Editor Configuration

**Zed:**
```json
{
  "agent": {
    "default_model": {
      "provider": "arifos",
      "model": "arifOS-APEX"
    }
  }
}
```

**VS Code: (ACP Extension):**
```json
{
  "acp.agents": [{
    "name": "arifOS-VPS",
    "command": ["ssh", "root@your-vps", "python -m arifosmcp.transport.acp_server"]
  }]
}
```

### Security Architecture

| Floor | LSP Protection | ACP Protection |
|-------|---------------|----------------|
| **F12** | `_sanitize_path()` blocks traversal | Session tokens required |
| **F13** | N/A (read-only) | `approve_session()` sovereign gate |
| **F1** | All queries logged to VAULT999 | All prompts logged to VAULT999 |
| **F4** | Real symbols reduce entropy | Structured context reduces ambiguity |

**Files:**
- `arifosmcp/intelligence/lsp_bridge.py` — LSP client wrapper
- `arifosmcp/transport/acp_server.py` — ACP protocol server
- `arifosmcp/tools/lsp_tools.py` — MCP tool registration

---

## ⚖️ The 13 Constitutional Floors

The constitutional core lives in `core/shared/floors.py`. These are **mathematical thresholds** — not guidelines.

### Hard Floors (VOID on Violation — Execution Stops)

| Floor | Name | Threshold | Meaning |
|-------|------|-----------|---------|
| **F1** | **Amanah** (Sacred Trust) | Reversible | Actions must be reversible. Destructive requires F13 override. |
| **F2** | **Truth** (Fidelity) | τ ≥ 0.99 | Every claim requires verifiable, grounded evidence. |
| **F4** | **Clarity** (Entropy) | ΔS ≤ 0 | Output must reduce user confusion, not increase it. |
| **F7** | **Humility** (Uncertainty) | Ω₀ ∈ [0.03, 0.15] | The AI must explicitly state what it does not know. |
| **F11** | **Command Authority** | Verified | Every session requires a verified actor identity. |
| **F12** | **Injection Defense** | Risk < 0.85 | External content wrapped in `<untrusted>` tags. |
| **F13** | **Sovereign** (Human Veto) | Human Signature | You are always in control. Humans hold the ultimate veto. |

### Soft Floors & Mirrors (PARTIAL on Violation — Warning Issued)

| Floor | Name | Threshold | Meaning |
|-------|------|-----------|---------|
| **F5** | **Peace²** (Stability) | P² ≥ 1.0 | Favors non-destructive, de-escalating paths. |
| **F6** | **Empathy** (Stakeholder) | κᵣ ≥ 0.70 | Considers impact on the weakest stakeholder. |
| **F9** | **Anti-Hantu** | C_dark < 0.30 | **No spiritual cosplay.** AI cannot claim consciousness or a soul. |
| **F3** | **Quad-Witness** (Consensus) | W₄ ≥ 0.75 | Human + AI + Earth + Ψ-Shadow. BFT n=4,f=1. 3/4 approval. |
| **F8** | **Genius** (APEX) | G ≥ 0.80 | Output of the thermodynamic G equation. |
| **F10** | **Ontology Lock** | Boolean | Protects system categorization. |

---

## 🛡️ Thermodynamic Governance & Temporal Grounding

arifOS does not use soft prompts. It uses **thermodynamic governance** derived from the **APEX Theory**.

### The APEX Theorem (G)

Every major decision generates a **Genius Score (G)**:

$$G^\dagger = (A \cdot P \cdot X \cdot E^2) \cdot \frac{|\Delta S|}{C}$$

| Variable | Meaning | Range |
|----------|---------|-------|
| **A** | Akal (Logical accuracy) | [0,1] |
| **P** | Presence (Temporal Stability/Peace) | [0,1] |
| **X** | Exploration (Knowledge) | [0,1] |
| **E** | Energy (Effort) | [0,1] |

If a proposed action scores `A=0.9, X=0.9` but is destructive `P=0.1`: **G = 0.08**. Since `0.08 < 0.80`, the action is a constitutional violation and rejected.

### ⏳ Temporal Grounding & Metabolic Flux (v2026.03.12)

> *"Zero-time truth is hallucination."*

arifOS now enforces **Temporal Hardening**. The kernel monitors its own **Metabolic Flux** (Tokens/sec). If the system exceeds human cognitive limits (500 tps) or detects clock jitter, the **Presence (P)** dial is automatically dampened.

The **Landauer Bound** ensures that every bit of "truth" requires a minimum energy cost ($E \geq n \times k_B \times T \times \ln(2)$). Claims that cost nothing computationally are immediately marked **VOID**.

---

## 🛠️ Canonical 8-Tool Sovereign Stack

The arifOS kernel exposes 8 core tools that form the "Sensory-Reasoning-Action" loop. Every call is governed by the 13 Floors.

| Tool | Entrypoint | Stage | Purpose |
|------|------------|-------|-------------|
| **`arifOS_kernel`** | `runtime` | `444` | **Main Brain**: Orchestrates the full metabolic loop. |
| **`search_reality`** | `senses` | `111` | **Grounding**: Proactively searches the real world (F2). |
| **`ingest_evidence`** | `senses` | `222` | **Intake**: Extracts raw truth from URLs and documents. |
| **`session_memory`** | `memory` | `555` | **Continuity**: Maintains long-term state and "Eureka Scars". |
| **`audit_rules`** | `law` | `333` | **Observability**: Inspect the active 13 Floor constraints. |
| **`check_vital`** | `metrics` | `000` | **Self-Awareness**: Reports system health and machine vitals. |
| **`open_apex_dashboard`** | `sites` | `888` | **Vision**: Launches the APEX UI for human-in-the-loop governance. |
| **`bootstrap_identity`** | `auth` | `000` | **Onboarding**: Anchors the session to a specific identity (F11). |

---

## ⚔️ arifOS vs. The Ecosystem

| Feature | LangChain / LlamaIndex | AutoGen / CrewAI | OpenAI Function Calling | **arifOS** |
|---------|------------------------|------------------|------------------------|------------|
| **Primary Purpose** | Tool chaining & RAG | Multi-agent conversation | API routing | **Constitutional safety** |
| **Execution Governance** | ❌ Manual | ❌ Custom logic | ❌ None | **✅ Automatic (13 Floors)** |
| **Hard Safety Gates** | ❌ None | ❌ None | ❌ None | **✅ 888_HOLD** |
| **Immutable Audit Ledger** | ❌ None | ❌ None | ❌ None | **✅ VAULT999 (Merkle DB)** |
| **Thermodynamic Eval** | ❌ None | ❌ None | ❌ None | **✅ APEX G = A×P×X×E²** |
| **TypeScript SDK** | ✅ Yes | ✅ Yes | ✅ Yes | **✅ @arifos/mcp** |
| **MCP Native** | ✅ Via plugin | ❌ Custom | ❌ Custom | **✅ Core protocol** |
| **Human Veto** | ❌ None | ❌ None | ❌ None | **✅ F13 Sovereign** |

> If you are building a prototype, use LangChain. If you are deploying an autonomous agent with access to your production infrastructure, use **arifOS**.

---

## 🚀 Installation & Quickstart

### Option 1: Python / PyPI (Quick Start — 2 Minutes)

```bash
# Install arifOS MCP
pip install arifosmcp

# Run MCP server (stdio - for Claude Desktop, Cursor IDE)
python -m arifosmcp.runtime stdio
```

**MCP Config for Claude Desktop:**
```json
{
  "mcpServers": {
    "arifos": {
      "command": "python",
      "args": ["-m", "arifosmcp.runtime", "stdio"],
      "env": {
        "ARIFOS_GOVERNANCE_SECRET": "YOUR_SECRET_KEY"
      }
    }
  }
}
```

### Option 2: Docker (Full Civilization Stack)

```bash
# Clone repository
git clone https://github.com/ariffazil/arifosmcp.git && cd arifosmcp

# Configure environment
cp .env.example .env

# Deploy full civilization stack
docker compose up -d
```

**Production Stack:** MCP kernel, Access gateway, Postgres (VAULT999), Redis, Qdrant, Prometheus, Grafana, n8n.

### Option 3: TypeScript / npm

```bash
npm install @arifos/mcp
```

```typescript
import { createClient, ENDPOINTS } from '@arifos/mcp';

const client = await createClient({
  transport: 'http',
  endpoint: ENDPOINTS.VPS, // https://arifosmcp.arif-fazil.com/mcp
});
await client.connect();

await client.callTool('bootstrap_identity', { declared_name: 'Operator' });
const result = await client.callTool('arifOS_kernel', {
  query: 'Is this action safe?',
  risk_tier: 'medium',
  actor_id: 'operator',
});
console.log(result.response);
```

---

## 🔒 VAULT999: The Immutable Ledger

Governance is meaningless without an audit trail. VAULT999 is a production-grade cryptographic ledger.

- **State Field (Ψ):** Every action accumulates telemetry — entropy, peace score, empathy coefficient, confidence.
- **Verdict:** `888_JUDGE` issues `SEAL`, `SABAR`, `VOID`, `888_HOLD`, or `PARTIAL`.
- **Merkle Seal:** `seal_vault` takes the full session history + telemetry, generates a SHA-256 Merkle root hash.
- **Persistence:** Hash committed to PostgreSQL (authoritative) + Redis (hot cache).

If an AI causes harm, VAULT999 provides mathematical proof of which floor failed, what the telemetry read, and who authorized the action.

---

## 👑 Constitutional Authority

**Forged By:** [Muhammad Arif bin Fazil](https://arif-fazil.com) — 888_JUDGE

📧 [arifos@arif-fazil.com](mailto:arifos@arif-fazil.com) • 🐙 [GitHub](https://github.com/ariffazil) • 𝕏 [@ArifFazil90](https://x.com/ArifFazil90)

---

***Ditempa Bukan Diberi* — Forged, Not Given [ΔΩΨ | ARIF]**

**Version:** 2026.03.13-FORGED • **License:** AGPL-3.0-only

