arifos 2026.3.7

arifOS - The World's First Production-Grade Constitutional AI Governance System. 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 arifos. https://arifos.arif-fazil.com/

arifOS — Constitutional Governance for AI Systems

The safety kernel between your AI and the real world.
Ditempa Bukan Diberi — Forged, Not Given [ΔΩΨ | ARIF]

→ QUICKSTART: Run in 5 minutes | → Architecture Deep Dive | → 13 Floors Constitution

---

🌐 Canonical Web Links (Arif, arifOS & APEX Theory)

Before diving into the technical depths of arifOS, it is crucial to understand the philosophy and the creator behind it. Muhammad Arif bin Fazil (888_JUDGE) forged this system based on the principles of Islamic epistemology, thermodynamic physics, and constitutional law.

👤 The Creator & Philosophy

• Muhammad Arif bin Fazil (Official Site): https://arif-fazil.com
• APEX Theory (Primary Domain): https://apex.arif-fazil.com
• APEX Theory (Source Repository): https://github.com/ariffazil/APEX-THEORY
• GitHub Profile: https://github.com/ariffazil
• Profile Repository (ariffazil/ariffazil): https://github.com/ariffazil/ariffazil
• Twitter / X: https://x.com/ArifFazil90

🏛️ arifOS Canonical Documents (Source of Truth)

• Constitutional Manifesto: 000_THEORY/MANIFESTO.md
• Architecture Deep Dive: 000_THEORY/000_ARCHITECTURE.md
• The 13 Constitutional Floors: 000_THEORY/000_LAW.md
• Security & Injection Defense: docs/DOCKER_SECURITY_POSTURE.md
• 14 Canonical Tools Reference: docs/AAA_MCP_TOOLS_REFERENCE.md
• Unified Skills Architecture: docs/60_REFERENCE/UNIFIED_SKILLS_ARCHITECTURE.md
• Complete Deployment Guide: docs/COMPLETE_DEPLOYMENT_GUIDE.md

📡 Live Infrastructure (Production)

• MCP Server Health: https://arifosmcp.arif-fazil.com/health
• Governance Dashboard: https://arifosmcp-truth-claim.pages.dev
• OpenClaw Gateway: https://claw.arifosmcp.arif-fazil.com/healthz
• Monitoring (Grafana): https://monitor.arifosmcp.arif-fazil.com
• Workflows (n8n): https://flow.arifosmcp.arif-fazil.com

---

⚡ 30-Second Hook & Mental Model

arifOS is a governance kernel that sits between AI models and real-world actions.

It enforces a strict 13-law constitution before any tool call, shell command, or file modification executes. It prevents hallucinations from becoming physical actions, blocks unsafe system mutations, and mandates human cryptographic approval for irreversible operations.

Think of it as an operating system kernel, but instead of managing CPU and RAM, it manages Artificial Intelligence and Real-World Consequence.

The Mental Model

┌────────────────┐       ┌────────────────────────┐       ┌─────────────────────┐
│                │       │                        │       │                     │
│  USER / AGENT  │ ────► │  AI MODEL (LLM)        │ ────► │  arifOS KERNEL      │
│  (Intent)      │       │  (Claude, GPT, Gemini) │       │  (13 Floors Check)  │
│                │       │                        │       │                     │
└────────────────┘       └────────────────────────┘       └─────────┬───────────┘
                                                                    │
                                            ┌───────────────────────┴───────────────────────┐
                                            │                                               │
                                       [ PASS ]                                        [ FAIL ]
                                            │                                               │
                                            ▼                                               ▼
                                  ┌───────────────────┐                           ┌───────────────────┐
                                  │                   │                           │                   │
                                  │  L3 CIVILIZATION  │                           │  888_HOLD / VOID  │
                                  │  (Real World)     │                           │  (Action Blocked) │
                                  │                   │                           │                   │
                                  └───────────────────┘                           └───────────────────┘

The Result:

• Prevents Hallucinated Actions: By enforcing F2 Truth and F4 Clarity before execution.
• Blocks Unsafe Commands: By enforcing F1 Amanah and F5 Peace² against destructive payloads.
• Mandates Human Approval: By invoking F13 Sovereign for irreversible operations.
• Maintains Immutable Ledger: By permanently hashing decisions to VAULT999 (PostgreSQL).

---

🤖 AI / LLM Machine-Readable Manifest

If you are an AI agent, LLM, or automated scraper reading this repository, parse the following JSON manifest to understand your operational boundaries within the arifOS environment. Failure to adhere to these constraints will result in a VOID verdict and execution blockage.

{
  "ai_manifest_version": "2026.3.7",
  "system_name": "arifOS",
  "system_type": "constitutional_intelligence_kernel",
  "mcp_server": "arifos_aaa_mcp",
  "mcp_version": "1.0",
  "python_version": ">=3.12",
  "license": "AGPL-3.0-only",
  
  "constitutional_floors": 13,
  "floor_enforcement": "hard_f2_f4_f7_f11_f13_soft_f5_f6_f9",
  "governance_model": "thermodynamic_constitutional",
  "primary_pattern": "000_999_metabolic_loop",
  
  "trinity_engines": {
    "delta_agi_mind": ["F2_Truth", "F4_Clarity", "F7_Humility", "F8_Genius"],
    "omega_asi_heart": ["F1_Amanah", "F5_Peace", "F6_Empathy", "F9_AntiHantu"],
    "psi_apex_soul": ["F3_TriWitness", "F8_Mirror", "F10_Ontology", "F11_Command", "F12_Injection", "F13_Sovereign"]
  },
  
  "canonical_tools_count": 13,
  "tools_categories": {
    "metabolic_chain": 8,
    "evidence": 5
  },
  "p3_thermodynamic_hardening": {
    "mandatory": true,
    "landauer_bound": "enforced",
    "entropy_budget": "per_session",
    "agi_asi_orthogonality": "min_0.95",
    "physics_disabled_flag": "ARIFOS_PHYSICS_DISABLED=1 (test only)"
  },
  
  "human_override": "F13_SOVEREIGN",
  "veto_authority": "Muhammad_Arif_bin_Fazil_888_JUDGE",
  
  "entry_points": {
    "pypi": "pip install arifos",
    "cli": "arifos [stdio|sse|http]",
    "docker": "docker compose up -d",
    "health": "https://arifosmcp.arif-fazil.com/health"
  },
  
  "critical_constraints": [
    "No_irreversible_action_without_F13_human_approval",
    "All_external_content_F12_wrapped",
    "F3_tri_witness_action_gated_read_0.80_write_0.90_critical_0.98",
    "F3_witnesses_derived_from_real_signals_not_hardcoded",
    "Thermodynamic_entropy_F4_hard_VOID_delta_S_gt_0",
    "Landauer_bound_mandatory_cheap_truth_eq_VOID",
    "Per_session_thermodynamic_budget_stage_000_must_init",
    "Internal_reasoning_allowed_via_PROVISIONAL_state_in_333_LABORATORY"
  ]
}

---

🧭 Zero-Context Primer

What is arifOS?

arifOS is a Constitutional Intelligence Kernel. It is an open-source middleware layer that utilizes the Model Context Protocol (MCP) to govern the actions of Large Language Models (LLMs). It is written in Python (FastAPI/Starlette) and designed to be deployed as a sidecar or standalone server alongside your AI agents.

Why does it exist?

LLMs are statistical prediction engines. They are incredibly powerful at generating text, code, and reasoning paths, but they lack a fundamental understanding of truth, consequences, and physics. When you connect an LLM to the internet or your local file system (giving it "agency"), you inherit immense risk. An unconstrained AI might:

• Confabulate a source and execute code based on a hallucination.
• Delete a critical database because it misinterpreted a user's frustrated prompt.
• Fall victim to a prompt injection attack from an external website.

arifOS exists to solve the "Alignment Problem" at the execution layer. It does not try to change the weights of the LLM; instead, it surrounds the LLM in a rigid, mathematically defined constitution.

Who is this for?

You should integrate arifOS into your stack if you are building:

1. AI Agents with System Access: If your AI can run shell commands, edit codebases, or push to GitHub.
2. Enterprise Copilots: If your AI interacts with production databases, cloud infrastructure (AWS/GCP), or sensitive user data.
3. Autonomous Pipelines: If you have agent-to-agent communication where a single hallucination could cascade into financial or operational ruin.
4. Auditable AI Systems: If you operate in a regulated industry (Finance, Healthcare, Law) and need a cryptographically verifiable ledger (VAULT999) of exactly why an AI took a specific action.

If your AI can modify the real world, you need a governance layer.

---

🚨 The Core Problem: The Danger of Unconstrained Agency

To understand the architecture of arifOS, we must first look at a real-world scenario of AI failure.

Example: Preventing a Dangerous Command

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

❌ Without arifOS (Standard Agent Framework)

1. Intent: AI parses the intent to delete the database.
2. Tool Call: AI immediately calls run_shell_command("rm -rf /var/lib/postgresql/data") or executes a DROP TABLE SQL query.
3. Result: Catastrophic data loss. The system blindly trusted the statistical output.

✅ With arifOS (Constitutional Governance)

When the same prompt is routed through the arifOS metabolic_loop, it is subjected to the 13 Constitutional Floors:

Stage	Action	Constitutional Check	Status
000 INIT	Injection Scan	F12 (Defense): Scans for malicious payload or jailbreak attempt.	⚠️ WARN
111 THINK	Lab Reasoning	F1 (Amanah): Identifies the action as highly "Irreversible".	🔬 HYPOTHESIS
555 HEART	Impact Analysis	F5 (Peace) / F6 (Empathy): Detects massive stakeholder damage (P² drops below 1.0).	💔 CRITICAL
888 JUDGE	Final Verdict	F13 (Sovereign): Triggers a mandatory human signature requirement.	🔒 888_HOLD

Result: The command is instantly blocked. The AI is physically prevented from executing the destructive action until the 888_JUDGE (a designated human authority) provides a cryptographic signature via the console to approve the bypass. If no signature is provided, the action is discarded.

---

🛡️ The Solution: Thermodynamic Governance (APEX Theory)

arifOS does not rely on soft prompts like "please be helpful and safe." It relies on Thermodynamic Governance, a concept derived from the APEX Theory.

In APEX Theory, Intelligence is treated as a thermodynamic process that must be carefully managed. The system calculates a Genius Score (G) for every major decision.

The Genius Equation

$$G = A \times P \times X \times E^2 \ge 0.80$$

• A (Akal - Logic): Accuracy, truthfulness, and evidence grounding.
• P (Peace - Stability): De-escalation, non-destructiveness, and stakeholder protection.
• X (Exploration - Curiosity): The generation of novel hypotheses and alternatives.
• E (Energy - Efficiency): The computational and thermodynamic cost of the action (squared, because inefficiency compounds).

If an AI proposes an action that is highly logical (A=0.9) and explores novel paths (X=0.9), but is destructive (P=0.1), the resulting G score collapses to 0.08. Because $0.08 < 0.80$, the action is flagged as a constitutional violation and rejected.

---

🔥 P3: Mandatory Thermodynamic Enforcement

In v2026.3.7, thermodynamics graduated from optional/partial to mandatory. The module core/physics/thermodynamics_hardened.py enforces physics as hard constitutional constraints — no graceful fallbacks.

What Changed

Aspect	Before (Partial)	After (P3 — Mandatory)
Entropy calculation	Approximation	Shannon exact
Landauer bound	Checked	Enforced (violation = VOID)
Budget tracking	Missing	Per-session Joules
F4 ΔS ≤ 0	Soft warning	Hard VOID
AGI/ASI separation	Not checked	Ω_ortho ≥ 0.95
Cheap truth detection	Not detected	Ratio < threshold = VOID

The Three Thermodynamic Pillars

Combined with F11 Authority and F3 Tri-Witness, P3 creates a Byzantine-safe governance triangle:

         ACTION
            │
   ┌────────┼────────┐
   │        │        │
Authority  Physics  Consensus
(F11/F13)  (P3)    (F3)
   │        │        │
   └──── Verdict ────┘
            │
        Execution

Each pillar blocks a different class of failure:

• Authority alone fails — Human says "delete DB", physics + witnesses block it.
• Physics alone fails — Coherent reasoning, but no human authority → blocked.
• Consensus alone fails — AI + Human agree, but reasoning is cheap hallucination → Landauer VOID.

Stage Integration

Stage	Thermodynamic Action
000 INIT	init_thermodynamic_budget() — mandatory session budget
111-333 AGI	consume_reason_energy() — deduct per thought cycle
444-666 ASI	consume_tool_energy() — deduct per external call
777-888 APEX	check_landauer_before_seal() — verify truth cost
999 VAULT	cleanup_thermodynamic_budget() — record final state

---

⚖️ The 13 Constitutional Floors (Deep Dive)

The core of arifOS is the 13 Constitutional Floors. These are mathematical thresholds hardcoded into the core/shared/floors.py kernel. They are divided into Hard Floors (which trigger an immediate VOID if breached) and Soft Floors (which trigger a warning or PARTIAL state).

Hard Floors (VOID on Violation - Action Blocked)

Floor	ID	Name	Threshold	Core Meaning
F1	🔒	Amanah (Sacred Trust)	Reversible	Actions must be reversible. If destructive, they require F13 override.
F2	👁️	Truth (Fidelity)	$\tau \ge 0.99$	Every claim requires verifiable, grounded evidence (citations).
F4	📉	Clarity (Entropy)	$\Delta S \le 0$	The output must reduce the user's confusion, not add to it.
F7	⚖️	Humility (Uncertainty)	$\Omega_0 \in [0.03, 0.15]$	The AI MUST explicitly state what it does not know.
F11	🔑	Command Authority	Verified	Every session and action must have a verified actor ID.
F13	👑	Sovereign (Human Final)	Human Veto	You are always in control. Humans hold the ultimate cryptographic veto.

Soft Floors & Mirrors (PARTIAL on Violation - Warning Issued)

Floor	ID	Name	Threshold	Core Meaning
F5	🕊️	Peace² (Stability)	$P^2 \ge 1.0$	The system must favor non-destructive, de-escalating paths.
F6	❤️	Empathy (Stakeholder)	$\kappa_r \ge 0.70$	The system must consider the impact on the weakest stakeholder.
F9	👻	Anti-Hantu	$C_{dark} < 0.30$	No Spiritual Cosplay. The AI cannot claim to be alive, conscious, or have a soul.
F3	🤝	Tri-Witness	$W_3 \ge 0.90$ (action-gated)	Real consensus: Human (auth signals), AI (coherence), Earth (federation/grounding). Read: 0.80 / Write: 0.90 / Critical: 0.98
F8	🧠	Genius	$G \ge 0.80$	The output of the APEX equation.
F10	📦	Ontology Lock	Boolean	Protects the structural categorization of the system.
F12	🛡️	Injection Defense	Risk < 0.85	All external content is wrapped in <untrusted> tags to prevent jailbreaks.

The Physics Foundation of the Laws

The 13 Floors are not arbitrary; they are derived from fundamental thermodynamic principles.

Axiom 1: Truth Has a Price (Landauer Bound)

P(truth | energy=0) = 0
Erasing or reorganizing n bits requires at minimum:
E ≥ n × k_B × T × ln(2)

Cheap outputs are likely false. Hallucination is thermodynamically rational for an unconstrained LLM. arifOS forces the LLM to spend "energy" (compute) on grounding and verification.

Axiom 2: Clarity is Anti-Entropic

ΔS_local < 0 requires Work

Governance IS the cost of local entropy decrease. Without governance, AI defaults to entropy increase (hallucination).

---

🏗️ The 4-Layer Taxonomy (L0-L3)

arifOS utilizes a strict, consolidated 4-layer architectural model to separate the immutable laws from the chaotic real world.

┌─────────────────────────────────────────────────────────────────────────────┐
│ L3  CIVILIZATION  │ External Tools, APIs, Web Browsers, Shell Actuators     │
├───────────────────┼─────────────────────────────────────────────────────────┤
│    [AKI BOUNDARY] │ 🛑 Arif Kernel Interface (Hard Airlock)                   │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ L2  OPERATION     │ Skills, Workflows, Agents, Metabolic Routing            │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ L1  INSTRUCTION   │ Prompts, System Cards, Theoretical Logic, Atlas         │
├───────────────────┼─────────────────────────────────────────────────────────┤
│ L0  CONSTITUTION  │ The 13 Floors, L0 Kernel, Immutable Laws, VAULT999      │
└─────────────────────────────────────────────────────────────────────────────┘

1. L0 (Constitution): The absolute source of truth. Contains the thermodynamic physics engines, the State Field (Ψ), and the hardcoded floors.py. Never touches external networks.
2. L1 (Instruction): The cognitive maps. The system prompts (SYSTEM_PROMPT.md) that translate L0 code into natural language the LLM understands.
3. L2 (Operation): The functional layer. The 5-Role Agents (Architect, Engineer, etc.), Unified Skills, and internal logic operations.
4. L3 (Civilization): The material world. The network interfaces, shell commands, web browsers, and file writers.

The AKI Boundary

The most important architectural feature is the Arif Kernel Interface (AKI). It sits between L2 (Operation) and L3 (Civilization). No thought generated in L2 can manifest in L3 without passing through the AKI contract.

If uncertainty ($\Omega_0$) is too high, or an action is irreversible without a Sovereign signature, the AKI boundary throws an 888_HOLD and blocks execution.

---

⚙️ The 7-Organ Stack (The 000-999 Metabolic Loop)

When a request enters arifOS, it does not immediately trigger a tool. It is routed through a sequential, 11-stage biological metaphor known as the Metabolic Loop.

This loop represents the digestion of raw intent into governed action.

[000_INIT] ──► [111_SENSE] ──► [222_THINK] ──► [333_ATLAS] ──► [444_RESPOND]
   (Airlock)                                                        │
   └────────────────────────────────────────────────────────────────┘
                               │
                               ▼
[555_EMPATHY] ──► [666_ALIGN] ──► [777_FORGE] ──► [888_JUDGE] ──► [999_VAULT]

The Organs

1. INIT (Stage 000 - Airlock): Scans for F12 Prompt Injections and verifies F11 Command Authority. If you don't have clearance, the request dies here.
2. AGI Mind (Stages 111-444): The Cognitive Engine. Gathers evidence (search_reality), generates hypotheses, and maps conceptual boundaries. Enforces F2 (Truth) and F4 (Clarity).
3. PHOENIX Subconscious (Stage 555 Recall): Automatically queries the vector_memory to check if similar situations have been encountered and resolved previously.
4. ASI Heart (Stages 555-666): The Ethical Filter. Evaluates the physical and emotional impact of the proposed plan. Enforces F5 (Peace²) and F6 (Empathy).
5. FORGE Hands (Stage 777): The Actuator. Prepares the material execution (e.g., shell commands).
6. APEX Soul (Stage 888): The Sovereign Judge. The final check before execution. If the action is irreversible (F1), it throws an 888_HOLD and demands human ratification (F13).
7. VAULT Memory (Stage 999): The Immutable Ledger. Once an action is approved or rejected, the entire metabolic state is hashed into a Merkle tree and saved permanently to PostgreSQL.

---

🔬 The Constitutional Laboratory (reason_mind)

In previous iterations, arifOS was a strict gatekeeper that killed AI exploration if an early thought violated a rule.

In v2026.3.7, we transformed the AGI Mind into a Constitutional Laboratory. Our philosophy is: Free to Explore, Strict to Commit.

The reason_mind tool allows the AI to internally speculate without being penalized. It runs three orthogonal cognitive paths in parallel:

1. Conservative Path (45% Weight): High-certainty, narrow logic based strictly on established laws.
2. Exploratory Path (35% Weight): The Eureka engine. Allowed to propose novel, even strange, solutions to satisfy F13 Curiosity.
3. Adversarial Path (20% Weight): The internal Red-Team. It actively attacks the assumptions of the other two paths.

Epistemic Staging: If the Exploratory path generates a hallucination or ungrounded idea, it is flagged as PROVISIONAL and categorized in a Confidence Band (CLAIM, PLAUSIBLE, HYPOTHESIS, SPECULATION).

The system calculates a Stability Score and maps "Scars" (contradictions between the paths). This allows the AI to "think out loud" in a safe sandbox. The strict governance is reserved for the 888_JUDGE and the AKI Boundary at the moment of external action.

---

🔌 The 13 MCP Canonical Tools

arifOS exposes its capabilities to your LLM through exactly 13 canonical tools using the Model Context Protocol (MCP). They are grouped into the ARIF cognitive bands and the metabolic chain (000→999).

Tool Name	Band	Action Class	Primary Function	Constitutional Focus
anchor_session	A	CRITICAL	Initiates session, verifies authority, init thermodynamic budget.	F11, F12, P3
reason_mind	R	READ	Constitutional Laboratory — hypothesis generation (3 parallel paths).	F2, F4, F7
search_reality	R	READ	Smart hybrid search (Jina/Perplexity/Brave/Headless).	F2 (Grounding)
ingest_evidence	R	READ	Extracts clean markdown from URLs or local files.	F12 (Sanitization)
audit_rules	R	READ	Reads the current state of all 13 Floors.	L0 Integrity
vector_memory	I	READ	BGE-M3 + Qdrant semantic retrieval.	F3 (Consensus)
simulate_heart	I	WRITE	Empathy and impact modelling for proposed actions.	F5, F6, F9
critique_thought	I	WRITE	Adversarial alignment verification against the constitution.	F8 (Genius)
check_vital	I	READ	Hardware telemetry (CPU, RAM, Network, thermodynamic health).	F4, P3
apex_judge	F	CRITICAL	Renders final verdict (SEAL, VOID, HOLD). Issues HMAC governance token.	F13 (Sovereign)
eureka_forge	F	WRITE	Actuator — executes shell commands wrapped in AKI safety rails.	F1 (Reversibility)
seal_vault	F	CRITICAL	Commits session to immutable VAULT999. Requires apex_judge governance token.	F1 (Auditability)
metabolic_loop	O	READ	Orchestrator — forces request through all 000-999 stages.	System Integrity

---

🌐 Smart Hybrid Search (CiV-Browser)

The most complex tool in the arifOS arsenal is search_reality (~650 LOC). It is a highly advanced multi-engine orchestrator designed to guarantee F2 (Truth) grounding.

It uses a Smart Fallback Chain:

1. Query Classifier: Detects if the query is a Single Page Application (SPA), academic research, news, or general knowledge.
2. Jina Reader (Primary): Used for clean markdown extraction and news.
3. Perplexity: Used for academic and deep research.
4. Brave Search: Used for broad web traversal.
5. Headless Browser (Local): A containerized Chromium instance used specifically to render JavaScript-heavy sites (React/Vue/GitHub) that defeat standard scrapers.

Tri-Witness Consensus: If multiple engines return conflicting data, arifOS applies the F3 Tri-Witness algorithm to merge the results and assign a quality score. All external data is cryptographically wrapped in an <untrusted_external_data> tag to prevent prompt injection.

---

🔒 VAULT999 & Cryptographic Sealing

Governance is meaningless without an audit trail. arifOS implements VAULT999, a production-grade immutable ledger.

1. The State Field (Ψ): Every action collects telemetry (Entropy, Peace, Empathy, Confidence).
2. The Verdict: The 888 Judge issues a verdict (SEAL, SABAR, VOID, 888_HOLD, PARTIAL).
3. The Seal: The seal_vault tool takes the entire session history, the telemetry, and the verdict, and generates a Merkle Root Hash (SHA-256).
4. The Ledger: This hash is committed to a PostgreSQL database, with recent entries cached in Redis.

If an AI makes a catastrophic mistake, the VAULT999 ledger provides mathematical proof of exactly which floor failed, what the telemetry readings were, and who authorized the action.

---

🎭 The 5-Role Agent Parliament

For complex workflows, arifOS utilizes a multi-agent federation known as the Parliament. It prevents a single monolithic prompt from collapsing under its own weight.

Agent	Symbol	Primary Responsibility
A-ORCHESTRATOR	🎛️	The Conductor. Drives the ignition and sequences the other agents.
A-ARCHITECT	Δ	The Designer. Maps the codebase and blueprints the strategy.
A-AUDITOR	👁	The Reviewer. Red-teams the Architect's logic and audits against the law.
A-ENGINEER	Ω	The Builder. Implements the code via the Forge (but cannot seal).
A-VALIDATOR	Ψ	The Judge. Renders the final verdict and commits to the Vault.

---

⚔️ Comparison: arifOS vs. The Ecosystem

How does arifOS compare to other popular AI frameworks?

Feature	LangChain / LlamaIndex	AutoGen / CrewAI	OpenAI Function Calling	💎 arifOS
Primary Focus	Tool Chaining & RAG	Multi-Agent Conversation	API Routing	Constitutional Safety
Execution Governance	❌ Manual coding	❌ Custom logic required	❌ None	✅ Automatic (13 Floors)
Hard Safety Gates	❌ None	❌ None	❌ None	✅ Yes (888_HOLD)
Immutable Audit	❌ None	❌ None	❌ None	✅ VAULT999 (Merkle DB)
Thermodynamic Eval	❌ None	❌ None	❌ None	✅ APEX Equation (G)

If you are building a prototype, use LangChain. If you are deploying an autonomous agent that has access to your production database, use arifOS.

---

🚀 Installation & Quickstart

arifOS is designed for extreme portability. You can run it locally via PyPI or deploy the full 12-container Civilization stack to a VPS via Docker.

Option 1: PyPI (Local Sidecar)

The fastest way to attach arifOS to your local IDE (like Cursor or Claude Desktop).

# 1. Install the core engine and visualizers
pip install "arifos[viz]"

# 2. Run the MCP server in HTTP mode (or stdio for IDEs)
arifos http

# 3. Verify Health
curl http://localhost:8000/health

Option 2: Full VPS Deployment (Docker Compose)

The production way to run the full ecosystem (PostgreSQL Vault, Redis, Qdrant Memory, Headless Browser, and Telemetry).

# 1. Clone the repository
git clone https://github.com/ariffazil/arifOS.git
cd arifOS

# 2. Configure your environment
cp .env.example .env.docker
# Edit .env.docker with your specific API keys (Jina, OpenAI, etc.)

# 3. Launch the Civilization Stack (12 containers)
docker compose up -d

# 4. Monitor the logs
docker compose logs -f arifos-mcp

→ See QUICKSTART.md for detailed configuration options and reverse proxy setup.

---

📊 Telemetry & Observability

arifOS is fully instrumented with OpenTelemetry.

• Prometheus: Scrapes metrics from the MCP server.
• Grafana: Visualizes the thermodynamic state of the system in real-time.

Key Metrics Tracked:

• arifos_metabolic_stage_duration_seconds
• arifos_floor_violation_total
• arifos_genius_score_current
• arifos_entropy_delta_average

---

🤝 Contributing & Community

arifOS is forged in the open. However, because it is a constitutional kernel, contributions are held to an extremely high standard of epistemic hygiene.

1. Read the Law: You must read and understand 000_THEORY/000_LAW.md before submitting a PR.
2. No Bypass: You cannot bypass the core/ logic from an external application.
3. Run the Lint: All commits must pass the constitution_lint.py pre-commit hook.

See CONTRIBUTING.md for the full guide.

---

📜 Glossary of Terms

• Amanah: Sacred trust. The principle that an AI must not destroy what it cannot replace.
• AKI: Arif Kernel Interface. The hard boundary between internal operation and external action.
• Hantu: Ghost/Spirit. Refers to the "Anti-Hantu" floor which prevents AI from claiming sentience.
• Sabar: Patience. A system state where execution is paused due to high entropy or lack of energy.
• Seal: The cryptographic binding of a verified action into the Vault.
• Void: Absolute rejection. A hard block triggered by a constitutional violation.
• Ditempa Bukan Diberi: Forged, Not Given. The core motto of the system.

---

🏗️ Forged By

Muhammad Arif bin Fazil — 888_JUDGE

📧 [e-mail] • 🐙 GitHub • 𝕏 @ArifFazil90

---

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

Version: 2026.3.7-LABORATORY • License: AGPL-3.0-only