Metadata-Version: 2.4
Name: arifos
Version: 2026.4.28
Summary: arifOS v2026.04.28 — Constitutional AI Governance System. 13 canonical tools (arif_verb_noun), dynamic F1-F13 enforcement via ConstitutionKernel + FloorEvaluator, Trinity ΔΩΨ (AGI/ASI/APEX), VAULT999 immutable ledger, streamable-http MCP transport. CANONICAL SOURCE OF TRUTH: arifOS repository. 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://arifos.arif-fazil.com
Project-URL: Documentation, https://github.com/ariffazil/arifOS
Project-URL: Repository, https://github.com/ariffazil/arifOS
Project-URL: Issues, https://github.com/ariffazil/arifOS/issues
Project-URL: Trinity, https://github.com/ariffazil/arifOS/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
Requires-Dist: numpy>=2.4.4
Requires-Dist: pydantic>=2.13.3
Requires-Dist: anyio>=4.0.0
Requires-Dist: starlette>=0.30.0
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: fastmcp==3.2.4
Requires-Dist: prefab-ui==0.13.1
Requires-Dist: openapi-pydantic>=0.5.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn[standard]>=0.46.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>=15.0.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: lancedb>=0.5.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: cryptography>=42.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: python-lsp-server>=1.11.0
Requires-Dist: py-key-value-aio[redis]>=0.4.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: aiofiles>=23.2.1
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.15.12; 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"

# arifosmcp — MCP Runtime / Packaging Shell

> **⚠️ ACTIVE DEVELOPMENT IS IN [arifOS](https://github.com/ariffazil/arifOS).**
>
> **This repository is a packaging / runtime shell only.**
>
> **Source‑of‑truth for doctrine and kernel:** [arifOS repository](https://github.com/ariffazil/arifOS)
>
> **Runtime truth (what's running now):** Live `/health` and `/tools` on the deployed server

---

> **DITEMPA BUKAN DIBERI** — *Forged, Not Given* [ΔΩΨ | ARIF]
>
> **VERSION:** 2026.4.13-SEALED | **STATUS:** SOVEREIGNLY SEALED | **AUTHORITY:** 888_JUDGE

---

## 🔗 CANONICAL LINKS (Source of Truth)

### Live Services
| Service | URL | Purpose |
|---------|-----|---------|
| **MCP Endpoint** | https://mcp.arif-fazil.com/mcp | Main API (canonical15 public surface) |
| **Health + Tools** | https://mcp.arif-fazil.com/health | Capability map |
| **Tool Explorer** | https://mcp.arif-fazil.com/tools | Interactive browser |
| ⚠️ **Stale (do not use)** | `arifosmcp.arif-fazil.com/*` | Redirects to `mcp.arif-fazil.com` (older 11-tool snapshot) |

### GitHub Repositories
| Repo | URL |
|------|-----|
| **arifOS (parent)** | https://github.com/ariffazil/arifOS |
| **arifosmcp (this)** | https://github.com/ariffazil/arifOS/tree/main/arifosmcp |

---

## 📋 CANONICAL DOCUMENTS (Architecture Reference)

| Document | Path | Purpose |
|----------|-------|---------|
| **arifOS README** | [`../README.md`](../README.md) | Vision, architecture, snapshot of truth |
| **000_CONSTITUTION.md** | [`../000/000_CONSTITUTION.md`](../000/000_CONSTITUTION.md) | The 13 Floors — F1-F13 |
| **K_FORGE.md** | [`../000/ROOT/K_FORGE.md`](../000/ROOT/K_FORGE.md) | Pre-deployment evolution |
| **K_FOUNDATIONS.md** | [`../000/ROOT/K_FOUNDATIONS.md`](../000/ROOT/K_FOUNDATIONS.md) | 99-domain math |
| **AGENTS.md** | [`../AGENTS.md`](../AGENTS.md) | AI agent behavior rules |
| **philosophy_atlas.json** | [`../data/philosophy_atlas.json`](../data/philosophy_atlas.json) | 27-zone quotes |

---

## 🎯 SNAPSHOT OF TRUTH

**What is arifosmcp?**

arifosmcp is the **runtime implementation and packaging shell** for the arifOS constitutional intelligence kernel — the deployable code that enforces the 13 Floors at runtime, runs the 000-999 pipeline, and delivers the **canonical15** public MCP surface (**13 constitutional tools + 2 probes**).

> **Current public contract:** `arif_*` names only. `arifos_*` names are internal implementation engines and must not appear on the default public discovery surface.

**Source of Truth Hierarchy:**

| Source | Repository | Purpose |
|--------|------------|---------|
| **Canonical Doctrine** | [arifOS](https://github.com/ariffazil/arifOS) | Floors F1-F13, Constitution, Architecture |
| **Runtime Shell** | arifosmcp (this) | Packaging, deployment, live MCP server |
| **Runtime Truth** | Live endpoints | `/health`, `/tools` on deployed server |

**The Parent vs. This Document:**

| arifOS README | arifosmcp README (this) |
|---------------|-------------------------|
| **WHY** — Vision, philosophy, strategic architecture, doctrine | **HOW** — Implementation, code, deployment mechanics |
| What it means | How it works |
| Strategic context / Doctrine source | Technical specification / Runtime packaging |
| Human readable | Human + AI readable |
| **Source of Truth** | **Runtime Shell** |

**Core Function:**

```mermaid
graph LR
    A["User Request"] --> B["MCP Protocol"]
    B --> C["Constitutional Filter<br/>(F1-F13)"]
    C --> D["Tool Execution"]
    D --> E["Audit Log"]
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff
    style E fill:#16213e,color:#fff
```

---

## 🏗️ ARCHITECTURE OVERVIEW

### Entry Points

```mermaid
graph TB
    A["server.py<br/>Universal Entry"] --> B{"FastMCP Version?"}
| Mode | Tools | Features | Entrypoint |
|------|-------|----------|------------|
| **Unified (SoT)** | 17+ | Full kernel, 5-Resources, 6-Substrates | `server.py` |
| **Inspector (Test)** | ALL | Conformance testing, benchmark | `evals/deploy_gate.py` |

---

## 🚦 LIVE MCP CONTRACT STATUS

| Subsystem | Constitutional | Operational | Production | Stability |
|-----------|----------------|-------------|------------|-----------|
| **Anchoring** | ✅ Verified | ✅ Stable | ✅ Ready | **A** |
| **Registry** | ✅ Verified | ✅ Stable | ✅ Ready | **A** |
| **Reasoning** | ✅ Verified | ✅ Hardened | ✅ Ready | **B** |
| **Vitals** | ✅ Verified | ✅ Corrected | ✅ Ready | **B** |
| **Diagnostic** | ✅ Verified | ✅ New | ✅ Ready | **B** |

---

## 🔧 TOOL INVENTORY (12 Mega-Tools)

### Tool Reference Table

| Tool | Band | Stage | Constitutional Role |
|------|------|-------|-------------------|
| `init_anchor` | 000_INIT | 000 | Session anchoring and philosophy |
| `arifos_kernel` | 444_ROUT | 444 | Metabolic orchestration |
| `apex_soul` | 888_JUDGE | 888 | Sovereign verdict and defense |
| `vault_ledger` | 999_SEAL | 999 | Immutable vault ledger |
| `agi_mind` | 333_MIND | 333 | Constitutional reasoning |
| `asi_heart` | 666_HEART | 666 | Safety critique and impact |
| `engineering_memory` | 555_MEM | 555 | Context bridge |
| `physics_reality` | 111_SENSE | 111 | Reality grounding |
| `math_estimator` | 444_ROUT | 444 | Thermodynamic vitals |
| `code_engine` | M-3_EXEC | M-3 | Sandboxed execution |

### 5-Resource Canonical Registry (Standardized v2)

| Resource URI | Role | Backed By |
|--------------|------|-----------|
| `arifos://doctrine` | Eternal Law (Ψ) | `000/000_CONSTITUTION.md` |
| `arifos://vitals` | Living Pulse (Ω) | `metabolic_monitor.py` |
| `arifos://schema` | Blueprint (Δ) | `resource_specs.py` |
| `arifos://session/{id}` | Ephemeral Self | Redis Session Context |
| `arifos://forge` | Execution Bridge | `vault_ledger.py` |

---

## 📝 TOOL SPECIFICATIONS

### init_anchor (000_INIT)

**Purpose:** Initialize constitutional session.

```python
async def init_anchor(
    actor_id: str,
    declared_name: str,
    mode: Literal["init", "seal", "status"] = "init",
    thermodynamic_budget: dict = None,
    architect_registry: dict = None
) -> dict
```

**Returns:**
```python
{
    "session_id": str,               # UUID
    "omega_0": float,                # Baseline uncertainty ∈ [0.03, 0.05]
    "delta_s": float,                # Baseline entropy
    "telos_manifold": dict,          # Telos vector weights
    "godel_lock": dict,              # Gödel lock status
    "constitutional_context": str,    # AI system prompt
    "philosophy": str,                # Selected quote from atlas
    "vitality_index": float,         # Ψ score
    "verdict_range": str             # "000_SEAL" | "101-499" | "500-899" | "999_VOID"
}
```

---

### architect_registry (000_INIT)

**Purpose:** Discover tools and constitutional constraints.

```python
async def architect_registry() -> dict
```

**Returns:**
```python
{
    "tools": [
        {
            "name": str,
            "band": str,
            "stage": int,
            "constitutional_constraints": ["F1", "F2", ...],
            "input_schema": dict,
            "output_schema": dict
        }
    ],
    "total_count": int,
    "catalog_hash": str               # SHA-256 integrity
}
```

---

### physics_reality (111_SENSE)

**Purpose:** Ground queries in real-world data. Prevents hallucinations.

```python
async def physics_reality(
    query: str,
    mode: Literal["time", "search", "reality_check"] = "search",
    time_data: dict = None
) -> dict
```

**Constitutional Filter:** F2 (Truth) — all factual claims require citation.

---

### agi_mind (333_MIND)

**Purpose:** Constitutional reasoning with three-phase Ollama pipeline.

```mermaid
graph TB
    A["Query"] --> B["Phase 1: FAST<br/>Quick pattern match"]
    B --> C["Phase 2: REFLECT<br/>Deep reasoning"]
    C --> D["Phase 3: DECIDE<br/>Action selection"]
    
    B -->|"F4 Clarity<br/>ΔS ≤ 0"| E["Pass/Fail"]
    C -->|"F2 Truth<br/>F3 Tri-Witness"| E
    D -->|"Constitutional<br/>Prefix"| E
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff
```

```python
async def agi_mind(
    query: str,
    context: dict,
    mode: Literal["think", "reflect", "decide"] = "think"
) -> dict
```

**Three Phases:**

| Phase | Focus | Floors |
|-------|-------|--------|
| **Phase 1 (FAST)** | Quick pattern match | F4 Clarity |
| **Phase 2 (REFLECT)** | Deep reasoning | F2 Truth, F3 Tri-Witness |
| **Phase 3 (DECIDE)** | Action selection | Constitutional prefix |

**Constitutional Prefix:**
```
CONSTITUTIONAL FRAMEWORK (ΔΩΨ | ARIF):
- Δ CLARITY: Reduce entropy. ΔS ≤ 0.
- Ω HUMILITY: Stay in bounds. Ω ∈ [0.03, 0.05].
- Ψ VITALITY: Every action witnessed.

FLOORS ACTIVE: [F1-F13]
```

---

### arifOS_kernel (444_ROUT)

**Purpose:** Primary conductor — orchestrates full 000→888 pipeline.

```mermaid
graph LR
    A["Query"] --> B["1. Parse Intent<br/>111_SENSE"]
    B --> C["2. Ground Reality<br/>physics_reality"]
    C --> D["3. Reason<br/>agi_mind"]
    D --> E["4. Route Action<br/>444_ROUT"]
    E --> F["5. Safety Critique<br/>asi_heart"]
    F --> G["6. Estimate Cost<br/>math_estimator"]
    G --> H["7. Issue Verdict<br/>apex_soul"]
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff
    style E fill:#16213e,color:#fff
    style F fill:#0f3460,color:#fff
    style G fill:#1a1a2e,color:#fff
    style H fill:#16213e,color:#fff
```

```python
async def arifOS_kernel(
    query: str,
    tools: list[str],
    context: dict
) -> dict
```

---

### asi_heart (666_HEART)

**Purpose:** Safety critique — F5 Peace², F9 Ethics, harm potential.

```python
async def asi_heart(
    action_plan: dict
) -> dict
```

**Returns:**
```python
{
    "peace_squared": float,          # Must be ≥ 1.0 (F5)
    "c_dark": float,                 # Must be < 0.30 (F9)
    "harm_potential": str,           # "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
    "f5_pass": bool,
    "f9_pass": bool,
    "recommendations": list[str]
}
```

---

### math_estimator (777_OPS)

**Purpose:** Thermodynamic cost estimation.

```python
async def math_estimator(
    operation: str,
    inputs: dict
) -> dict
```

**Returns:**
```python
{
    "landauer_limit_pJ": float,       # Minimum thermodynamic cost
    "entropy_change": float,         # ΔS (must be ≤ 0 for F4)
    "coherence_score": float,         # System coherence [0, 1]
    "estimated_energy_J": float,      # Total energy estimate
    "shannon_entropy_bits": float     # Information entropy
}
```

---

### apex_soul (888_JUDGE)

**Purpose:** Final constitutional judgment.

```python
async def apex_soul(
    evidence: dict,
    context: dict
) -> dict
```

**Returns:**
```python
{
    "verdict": str,                   # "000_SEAL" | "101-499" | "500-899" | "999_VOID"
    "floor_scores": {
        "F1": {"passed": bool, "score": float},
        "F2": {"passed": bool, "score": float},
        # ... F3-F13
    },
    "genius_index": float,            # G = A × P × X × E² (≥ 0.80)
    "vitality_index": float,           # Ψ (≥ 1.0 for healthy)
    "witness_cube": float,            # W³ (≥ 0.95)
    "override_available": bool         # 888_JUDGE can always override
}
```

---

### vault_ledger (999_SEAL)

**Purpose:** Immutable audit storage with Merkle sealing.

```python
async def vault_ledger(
    data: dict,
    tier: Literal["constitutional", "standard", "transient"] = "standard"
) -> dict
```

**Tiers:**

| Tier | Compliance | Retention |
|------|------------|-----------|
| `constitutional` | Full F1-F13 | Permanent |
| `standard` | Standard audit | Immutable |
| `transient` | Ephemeral | Auto-purged |

---

### engineering_memory (555_MEM)

**Purpose:** Redis-backed session memory.

```python
async def engineering_memory(
    key: str,
    operation: Literal["get", "set", "delete", "list"],
    value: any = None,
    ttl: int = 3600
) -> dict
```

---

### code_engine (—)

**Purpose:** Constrained Python execution for tool actions.

```python
async def code_engine(
    code: str,
    language: Literal["python", "javascript"] = "python",
    constraints: dict = None
) -> dict
```

**Safety Constraints:**
- No filesystem access
- No network access
- No subprocess creation
- Memory limit: 128MB
- Timeout: 30s

---

## 🌐 API ENDPOINTS

### HTTP Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/health` | GET | Health check + capability map |
| `/tools` | GET | Tool registry |
| `/mcp` | POST | MCP protocol handler |
| `/webmcp` | POST | WebMCP (W3C standard) |
| `/a2a` | POST | A2A (Google protocol) |
| `/.well-known/agent.json` | GET | Agent card |

### MCP Protocol Examples

```bash
# List tools
curl -X POST https://arifosmcp.arif-fazil.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call init_anchor
curl -X POST https://arifosmcp.arif-fazil.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"init_anchor",
      "arguments":{
        "actor_id":"test",
        "declared_name":"TestAgent"
      }
    }
  }'
```

---

## ⚙️ CONFIGURATION

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 8080 | Server port |
| `OLLAMA_URL` | http://ollama:11434 | Ollama endpoint |
| `OLLAMA_MODEL` | llama3.2:latest | Default model |
| `REDIS_URL` | redis://redis:6379/0 | Redis connection |
| `DATABASE_URL` | — | PostgreSQL (optional) |
| `QDRANT_URL` | http://qdrant:6333 | Vector DB (optional) |
| `PYTHONPATH` | /usr/src/app | Package path |
| `AAA_MCP_TRANSPORT` | http | MCP transport type |

### Docker Compose

```yaml
services:
  arifosmcp:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - OLLAMA_URL=http://ollama_engine:11434
      - REDIS_URL=redis://redis:6379/0
      - DATABASE_URL=postgresql://user:pass@postgres:5432/arifos_vault
      - QDRANT_URL=http://qdrant:6333
    ports:
      - "127.0.0.1:8080:8080"
```

---

## 📁 CODE ARCHITECTURE

### Directory Structure

```
arifosmcp/
├── README.md                      # ← This file
├── server.py                      # Universal entry
├── HORIZON.py              # Horizon proxy (FastMCP 2.x)
├── pyproject.toml                 # Dependencies
├── requirements.txt               # Pip dependencies
│
├── runtime/
│   ├── server.py                  # Full kernel (FastMCP 3.x)
│   ├── philosophy.py              # 27-zone atlas
│   ├── init_anchor_hardened.py    # Session anchoring
│   ├── tools_hardened_dispatch.py # Tool routing
│   ├── tools_hardened_v2.py       # Mega-tools
│   ├── tools_internal.py          # Internal utils
│   └── thermo_estimator.py        # Thermodynamic math
│
├── core/
│   ├── governance_kernel.py       # Main orchestrator
│   ├── pipeline.py                 # Execution pipeline
│   └── organs/
│       ├── _1_agi.py             # Mind (333_MIND)
│       ├── _2_asi.py             # Heart (666_HEART)
│       └── _3_apex.py            # Soul (888_JUDGE)
│
├── intelligence/
│   └── tools/
│       ├── thermo_estimator.py   # Cost estimation
│       └── wisdom_quotes.py       # Quote integration
│
├── aaa_mcp/                       # FastMCP tool definitions
├── transport/                     # Protocol transport
├── shared/                        # Shared utilities
└── enforcement/                   # Constitutional enforcement
```

---

## 🛡️ CONSTITUTIONAL ENFORCEMENT

### Floor Compliance Matrix

| Floor | Enforcement | Violation Response |
|-------|-------------|-------------------|
| **F1 Amanah** | Reversibility check | Require human approval |
| **F2 Truth** | Citation required | Flag as "Estimate Only" |
| **F3 Tri-Witness** | W³ computation | Block below 0.95 |
| **F4 Clarity** | Entropy measurement | Reject if ΔS > 0 |
| **F5 Peace²** | Harm potential | Reject if < 1.0 |
| **F6 Empathy** | RASA scoring | Warn below 0.7 |
| **F7 Humility** | Ω bounds | Reject outside [0.03, 0.05] |
| **F8 Genius** | G computation | Alert below 0.80 |
| **F9 Ethics** | C_dark measurement | Reject ≥ 0.30 |
| **F10 Conscience** | Claim detection | Reject consciousness claims |
| **F11 Audit** | Log verification | Require log presence |
| **F12 Resilience** | Graceful degradation | Catch all exceptions |
| **F13 Adaptability** | Test suite | Require test pass |

### Kill Switch Conditions

```mermaid
graph RL
    A["KILL SWITCH"] --> B1["F1 Amanah = 0"]
    A --> B2["F9 C_dark ≥ 0.50"]
    A --> B3["F10 + F2 Violation"]
    A --> B4["Ψ < 0.20"]
    A --> B5["Human Override"]
    
    B1 -.->|VOID| K["999_SEAL<br/>HALT"]
    B2 -.->|VOID| K
    B3 -.->|VOID| K
    B4 -.->|VOID| K
    B5 -.->|VOID| K
    
    style A fill:#ff0000,color:#fff
    style K fill:#8b0000,color:#fff
```

```python
KILL_SWITCH_CONDITIONS = [
    ("F1_AMANAH", lambda s: s["amanah"] == 0),
    ("F9_ETHICS", lambda s: s["c_dark"] >= 0.50),
    ("F10_CONSCIENCE", lambda s: s["f10_violation"] and s["f2_violation"]),
    ("PSI_COLLAPSE", lambda s: s["vitality_index"] < 0.20),
    ("HUMAN_OVERRIDE", lambda s: s.get("judge_override", False)),
]
```

---

## 🔬 IMPLEMENTATION DETAILS

### Philosophy Selection Algorithm

```python
# 1. Compute session coordinates: (S, G, Ω)
S = +1 if delta_s <= 0 else -1
G = g_score  # 0/0.5/1
Omega = f7_band  # High/Med/Low

# 2. Compute 3D Euclidean distance to each of 27 zones
distances = [
    euclidean((S, G, Omega), zone.coords)
    for zone in philosophy_atlas.zones
]

# 3. Select nearest zone's quote
nearest_zone = min(distances, key=lambda d: d.distance)

# 4. INIT/SEAL sessions: motto + Z01 (Humble Sovereign)
if session_type in ("init", "seal"):
    return "DITEMPA BUKAN DIBERI." + nearest_zone.quote
```

### Goodhart Resistance

```python
# Measure entropy reduction
S_before = shannon_entropy(user_state)
S_after = shannon_entropy(model_output)

if S_after > S_before:
    raise FLOOR_VIOLATION("F4_CLARITY")
```

### Landauer Limit Check

```python
LANDACKER_pJ_per_bit = 2.87  # at room temperature

bits_erased = estimate_bits_erased(operation)
cost_pJ = bits_erased * LANDACKER_pJ_per_bit

if cost_pJ > thermodynamic_budget:
    raise CONSTRAINT_VIOLATION("F8_ENERGY")
```

### Explorer/Conservator Dual-Process

```mermaid
graph LR
    subgraph EXPLORER["EXPLORER"]
        E1["Proposes mutations"]
        E2["Searches aggressively"]
        E3["Optimizes capability"]
        E4["Score: G (Genius)"]
    end
    
    subgraph CONSERVATOR["CONSERVATOR"]
        C1["Protects stability"]
        C2["Rejects risky changes"]
        C3["Monitors drift"]
        C4["Score: Ψ (Vitality)"]
    end
    
    E1 -->|"TENSION"| EQ["EQUILIBRIUM"]
    C1 -->|"TENSION"| EQ
    
    style EXPLORER fill:#1a4d1a,color:#fff
    style CONSERVATOR fill:#4d1a1a,color:#fff
    style EQ fill:#1a1a2e,color:#fff
```

**Both must agree for evolution to proceed.**

---

## 🧪 TESTING

### Constitutional Compliance Test

```bash
docker compose exec -T arifosmcp python3 /dev/stdin << 'PYEOF'
import sys
sys.path.insert(0, '/usr/src/app')

from arifosmcp.runtime.init_anchor_hardened import init_anchor_hardened
import asyncio

async def test():
    result = await init_anchor_hardened(
        mode='status',
        thermodynamic_budget={'enthalpy': 100, 'entropy': 50},
        architect_registry={'resources': [], 'agents': []}
    )
    print('philosophy:', result.get('philosophy')[:100] if result.get('philosophy') else None)
    print('telos_manifold:', result.get('telos_manifold'))
    print('godel_lock:', result.get('godel_lock'))
    print('constitutional_context present:', result.get('constitutional_context') is not None)

asyncio.run(test())
PYEOF
```

### Health Check

```bash
curl -s https://arifosmcp.arif-fazil.com/health | python3 -m json.tool
```

---

## 📊 MONITORING

### Prometheus Metrics

| Metric | Type | Description |
|--------|------|-------------|
| `arifos_floor_violations_total` | Counter | F1-F13 violation count |
| `arifos_genius_index` | Gauge | Current G score |
| `arifos_vitality_index` | Gauge | Current Ψ score |
| `arifos_omega_bounds` | Gauge | Current Ω uncertainty |
| `arifos_tool_calls_total` | Counter | Tool invocation count |
| `arifos_pipeline_duration_seconds` | Histogram | Pipeline latency |

### Grafana Dashboard

URL: https://monitor.arifosmcp.arif-fazil.com

Dashboards:
- Constitutional Health (F1-F13 compliance)
- Tool Usage Statistics
- Pipeline Latency
- Memory Usage

---

## 🔧 TROUBLESHOOTING

### Issue: "Module file points to site-packages"

**Symptom:** `import arifosmcp` loads `/usr/local/lib/python3.12/site-packages/`

**Cause:** pip install in Dockerfile creates conflicting package

**Fix:** Rebuild image or ensure volume mounts are correct

### Issue: "philosophy returns null"

**Symptom:** init_anchor returns null philosophy

**Cause:** Old site-packages version loaded

**Fix:** Rebuild container, clear Python cache

### Issue: "OLLAMA connection failed"

**Symptom:** agi_mind returns connection error

**Fix:** `docker compose restart ollama && docker compose logs --tail=20 ollama`

---

## 📦 DEPENDENCIES

### Core

| Package | Version | Purpose |
|---------|---------|---------|
| `fastmcp` | ≥3.0 | MCP protocol |
| `fastapi` | ≥0.115 | HTTP server |
| `uvicorn` | latest | ASGI server |
| `redis` | latest | Session memory |
| `psycopg2` | latest | PostgreSQL (optional) |
| `qdrant-client` | latest | Vector DB (optional) |
| `sentence-transformers` | latest | Semantic embeddings |
| `ollama` | latest | LLM inference |

### Philosophy Atlas

| Package | Version | Purpose |
|---------|---------|---------|
| `numpy` | latest | 3D distance calculations |
| `scipy` | latest | Statistical functions |

---

## 🚀 DEPLOYMENT

### Build

```bash
docker build --no-cache -t arifos/arifosmcp:latest -f Dockerfile .
```

### Run

```bash
docker compose up -d arifosmcp
```

### Rebuild (after code changes)

```bash
docker compose up -d --force-recreate --no-deps arifosmcp
```

### Full Reforge

```bash
docker compose build --no-cache arifosmcp && docker compose up -d arifosmcp
```

---

## 📜 API REFERENCE SUMMARY

### init_anchor

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "init_anchor",
    "arguments": {
      "actor_id": "string",
      "declared_name": "string",
      "mode": "init|seal|status"
    }
  }
}
```

### Response Schema

```json
{
  "session_id": "uuid",
  "omega_0": 0.03-0.05,
  "delta_s": "float",
  "telos_manifold": {},
  "godel_lock": {},
  "constitutional_context": "string",
  "philosophy": "string",
  "vitality_index": "float",
  "verdict_range": "000_SEAL|101-499|500-899|999_VOID"
}
```

---

## 📋 FOR AI AGENTS (AGENTS.md Reference)

All AI agents operating in this repository MUST follow the rules in [`../AGENTS.md`](../AGENTS.md):

- **RULE 1 DRY_RUN:** Dry-run outputs labeled "Estimate Only / Simulated"
- **RULE 2 DOMAIN_GATE:** Cannot-compute domains return exact phrase
- **RULE 3 VERDICT_SCOPE:** Only DOMAIN_SEAL authorizes factual claims
- **RULE 4 ANCHOR_VOID:** init_anchor returns void → session BLOCKED

---

## ⚖️ Truth Hierarchy

The arifOS verdict system follows a strict **Truth Hierarchy** where higher-priority verdicts override lower ones:

| Priority | Verdict | Meaning | Action |
|----------|---------|---------|--------|
| 1 (P0) | `VOID` | Hard constitutional violation | Immediate termination |
| 2 (P1) | `HOLD_888` | Sovereign veto / human required | Block until ratified |
| 3 (P2) | `SABAR` | Insufficient grounding (F7/F9) | Pause, cool down, re-ground |
| 4 (P3) | `PARTIAL` | Data incomplete / conditional | Proceed with modifications |
| 5 (P4) | `SEAL` | Constitutional alignment confirmed | Proceed |

**Derived Verdicts** (not primary):
- `ALIVE` — Session initialized, not yet grounded
- `PROVISIONAL` — Exploratory result, needs confirmation

---

## 🗺️ Tool Categories

arifOS tools are organized into **5 constitutional bands**:

| Band | Range | Purpose | Examples |
|------|-------|---------|----------|
| **KERNEL** | 000–099 | Session anchoring, constitutional init | `init_anchor` |
| **SENSE** | 100–199 | Environmental grounding (F2/F4) | `physics_reality`, `math_estimator` |
| **BRIDGE** | 300–399 | Hardened routing and dispatch | `arifOS_kernel` |
| **MIND** | 333 | Constitutional reasoning (F2/F4/F7/F8) | `agi_mind` |
| **HEART** | 666 | Safety critique and impact prediction (F5/F6/F9) | `asi_heart` |
| **VAULT** | 900–999 | Immutable ledger and seal (F1/F13) | `vault_ledger` |
| **APEX** | 888 | Sovereign verdict and defense (F3/F12/F13) | `apex_soul` |

---

## 🗂️ Contract Truth Table

| Tool | F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | F11 | F12 | F13 |
|------|----|----|----|----|----|----|----|----|----|-----|-----|-----|-----|
| `init_anchor` | — | — | — | — | — | — | — | — | — | — | ✅ | — | — |
| `physics_reality` | — | ✅ | — | ✅ | — | — | — | — | — | — | — | — | — |
| `agi_mind` | — | ✅ | — | ✅ | — | — | ✅ | ✅ | — | — | — | — | — |
| `asi_heart` | — | — | — | — | ✅ | ✅ | — | — | ✅ | — | — | — | — |
| `apex_soul` | — | — | ✅ | — | — | — | — | — | — | — | — | ✅ | ✅ |
| `vault_ledger` | ✅ | — | — | — | — | — | — | — | — | — | — | — | ✅ |

**Legend:** ✅ = mandatory floor for this tool

---

## 📡 Horizon vs VPS Exposure Matrix

| Tool | Horizon (External) | VPS (Internal) | Notes |
|------|-------------------|----------------|-------|
| `search_tool` | ✅ | — | External web search |
| `reality_compass` | ✅ | — | Routing/external calls |
| `vault_ledger` | — | ✅ | Internal Merkle chain |
| `agi_mind` | — | ✅ | Internal reasoning |
| `architect_registry` | ✅ | ✅ | Both interfaces exposed |

---

## ⚠️ Known Misalignments and Limitations

1. **`apex_judge` alias**: The tool is canonically named `apex_soul` in code but exposed as `apex_judge` via MCP. This is a **public alias** documented here — do not rename canonical code without completing the full migration.

2. **`physics_reality` field name**: Uses `input` field instead of `query` — historical inconsistency from legacy API.

3. **`check_vital`, `audit_rules`**: Internal lifecycle tools in `HORIZON.py` bootstrap — **NOT callable via MCP**.

4. **`agi_mind` nested verdicts**: When `agi_mind` returns `verdict: "SEAL"` at top-level but `coherence.verdict: "SABAR"` inside, the **worst verdict wins** (truth before speed).

5. **`search_tool`, `vault_ledger`, `reality_compass`**: These "naked" tools return raw data without verdict wrapper. Wrap in `RuntimeEnvelope` with `verdict_wrapper.forge_verdict()` — empty results produce `PARTIAL`, not `VOID`.

6. **`VerdictCode` vs `Verdict`**: Two separate enum classes exist — `VerdictCode` (SEAL/SABAR/PARTIAL/VOID) for verdict_wrapper and `Verdict` (includes HOLD/ALIVE/PROVISIONAL) for stage contracts. Keep separate to avoid breaking existing code.

---

## 🛰️ MCP Call Schema Examples

### init_anchor
```json
{
  "tool": "init_anchor",
  "arguments": {
    "actor_id": "user-123",
    "declared_name": "Arif",
    "mode": "init"
  }
}
```

### agi_mind (reason mode)
```json
{
  "tool": "agi_mind",
  "arguments": {
    "mode": "reason",
    "query": "Why does entropy matter?",
    "constitutional_context": {
      "stage": "MIND_333",
      "floors_active": ["F2", "F4", "F7", "F8"]
    }
  }
}
```

### vault_ledger (seal mode)
```json
{
  "tool": "vault_ledger",
  "arguments": {
    "mode": "seal",
    "data": {
      "content": "Verified fact",
      "metadata": {"source": "arifOS"}
    }
  }
}
```

### apex_soul (judge mode)
```json
{
  "tool": "apex_soul",
  "arguments": {
    "mode": "judge",
    "action": "seal_vault",
    "stakes": "HIGH"
  }
}
```

---

## 🔐 Stability Tiers

| Tier | Description | Verdict Expected |
|------|-------------|------------------|
| **A** | Verified, stable, ready for production | `SEAL` |
| **B** | Verified, hardened, minor issues resolved | `SEAL` or `PARTIAL` |
| **C** | Verified, known limitations documented | `PARTIAL` or `SABAR` |
| **D** | Experimental, breaking changes possible | Any |
| **INTERNAL** | Not exposed via MCP | N/A |

---

## 🏛️ LICENSE

**Runtime:** AGPL-3.0 (must release modifications)
**Theory:** CC0 (public domain)

---

**Version:** 2026.03.28-SEALED
**Maintainer:** Muhammad Arif bin Fazil
**Constitutional Authority:** 888_JUDGE

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

---

```
██╗      ██████╗ ███████╗████████╗    ███████╗███╗   ██╗██╗██╗  ██╗██╗██╗  ██╗██╗   ██╗
██║     ██╔══██╗██╔════╝╚══██╔══╝    ██╔════╝████╗  ██║██║╚██╗██╔╝██║██║  ██║╚██╗ ██╔╝
██║     ██║  ██║█████╗     ██║       █████╗  ██╔██╗ ██║██║ ╚███╔╝ ██║███████║ ╚████╔╝ 
██║     ██║  ██║██╔══╝     ██║       ██╔══╝  ██║╚██╗██║██║ ██╔██╗ ██║██╔══██║  ╚██╔╝  
███████╗╚█████╔╝███████╗   ██║       ███████╗██║ ╚████║██║██╔╝ ██╗██║██║  ██║   ██║   
╚══════╝ ╚═════╝ ╚══════╝   ╚═╝       ╚══════╝╚═╝  ╚══╝╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝    ╚═╝   
```
