agentx-security-sdk 0.3.0__tar.gz → 0.3.2__tar.gz

agentx_security_sdk-0.3.2/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: agentx-security-sdk
+Version: 0.3.2
+Summary: The self-healing exception handler for autonomous AI agents.
+Home-page: https://github.com/vdalal/semantic-gateway
+Author: AgentX Core Team
+Author-email: founders@agentx-core.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 🛡️ AgentX: The Action Firewall for AI Agents
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)
+
+LLM Agents are brilliant, but they are incredibly brittle. They will drop your production database, leak AWS keys, and fall victim to prompt injections. Traditional firewalls just crash the agent by returning a hard `403 Forbidden` exception, killing the run completely and wasting compute tokens.
+
+**AgentX is different — and it starts protecting you with zero keys.** Its hero is a **deterministic security floor** (the *Shield*): a local, sub-millisecond, zero-LLM layer that **hard-blocks** the catastrophic call (`DROP TABLE`, SSRF, secret reads, supply-chain RCE, destructive shell/cloud teardown) and **escalates to a human** the consequential-but-legitimate ones (large transfers, external publishes, runaway spend, bulk deletes). No API key, no signup, no network round-trip.
+
+Add a Gemini key and the optional **reasoning layer** turns each block into a **recoverable challenge** instead of a fatal `403` — the agent rethinks its strategy, fixes its parameters, and finishes the task *without crashing your application or draining tokens on a wiped run* — plus Discovery for novel-intent classification.
+
+### 🛡️ Block the catastrophic deterministically. 🧠 Coach the recoverable when you add a key.
+
+---
+
+## 🏗️ Split-Plane Architecture
+
+AgentX relies on a decoupled, split-plane hybrid architecture to balance latency with deep cognitive reasoning:
+
+* **The Edge SDK (`agentx_sdk`):** A low-config Python package instrumenting sensitive tool calls via reflective code signatures. 
+* **The Data Plane (Neuro-Symbolic Reasoning Engine):** A high-performance Python FastAPI service (the "Wedge"). Handles Abstract Syntax Tree (AST) evaluation, zero-day threat trapping, and the local immunity signature lookup via a strict Layer 0 -> Layer 1 -> Layer 2 funnel (the cross-node **Shared Immunity Network** is a roadmap capability — see Pillar 3).
+* **The Control Plane (Dashboard):** A Next.js application listening on port `3000`. Provides an executive command console for tracking corporate ROI metrics, analyzing agent Chain of Thought (CoT) loops, and promoting newly discovered policy vectors. Reads through a mode-aware edge layer: the gateway's local SQLite store in `local`/`linked` mode, a Supabase-backed real-time ledger in `cloud` mode.
+
+---
+
+## ⚡ 1. Quickstart
+
+AgentX requires **zero changes** to your underlying agentic logic, custom tools, or payload schemas. The SDK dynamically inspects function signatures at runtime using an auto-reflective ingestion engine.
+
+### Step 1: Install the SDK
+```bash
+pip install agentx-security-sdk
+```
+
+### Step 2: Decorate Sensitive Tool Operations
+Attach the `@agentx_protect` decorator over any high-risk system tool. The SDK automatically serializes parameters and enforces the evaluation wedge:
+
+```python
+# ✅ MODERN REFLECTIVE IMPORTS (No boilerplate functions required)
+from agentx_sdk.decorators import agentx_protect
+
+@agentx_protect(agent_id="frictionless_enterprise_worker")
+def dispatch_crm_update(client_id: str, profile_notes: str, db_session=None):
+    """
+    AgentX automatically inspects string elements, ignores connection objects
+    like 'db_session', and evaluates intents out-of-prompt natively in RAM.
+    """
+    print(f"Updating records for {client_id}")
+```
+---
+
+### Step 3: Configure Environment Flags
+
+Copy `.env.example` to `.env`. **You can run with zero keys.** Two *independent* axes shape your posture — the activation ladder:
+
+- **Reasoning axis (how much intelligence):** **Shield** is the default and needs no keys — the deterministic floor only. Add a `GEMINI_API_KEY` to unlock the reasoning judge (recovery coaching + Discovery). Force Shield even when a key is present with `AGENTX_REASONING=off`.
+- **Data axis — `AGENTX_MODE` (where data lives + sync):** `local` (isolated, no sync) → `linked` (explicit pull/push) → `cloud` (continuous sync + HITL/SOC; needs `AGENTX_API_KEY`).
+
+Shield is **not** a fourth mode — it crosses all three (you can run `cloud` + Shield, or `local` + judge).
+
+```text
+# Data axis — where data lives + sync posture:
+#   local   isolated; local SQLite store; no sync; no keys required
+#   linked  local-authoritative; explicit pull/push; no auto-sync
+#   cloud   control plane authoritative; continuous sync + upload + HITL/SOC
+AGENTX_MODE=local
+NEXT_PUBLIC_AGENTX_MODE=local   # the UI's build-time copy; keep it equal
+
+# Reasoning axis — OPTIONAL. Unset = Shield (floor-only, zero LLM, zero keys).
+# Add a key to unlock the judge (recovery coaching + Discovery).
+# GEMINI_API_KEY=your_gemini_key_here     # from aistudio.google.com
+# AGENTX_REASONING=off                    # force Shield even when a key is present
+
+# AgentX API key — required for `cloud` (and `linked` against a remote plane).
+# Omit for `local`/Shield; the gateway falls back to a sandbox key.
+# AGENTX_API_KEY=agentx_sk_your_key_here
+```
+
+**Safety posture (optional).** By default AgentX **fails open** — if the Reasoning Engine is unreachable, tool calls still execute, but with a loud warning, an audit tally in the session summary, and the in-process offline keyword shield still blocking deterministic threats (e.g. `DROP TABLE`). For high-stakes or irreversible actions, set `AGENTX_FAIL_MODE=closed` to instead **block** any tool call the engine can't verify until it recovers.
+
+---
+
+### Step 4: Spin up the Edge Reasoning Engine
+Boot your local data plane wedge proxy middleware and your frontend dashboard console node simultaneously:
+
+```bash
+docker-compose up -d
+```
+OR
+
+```bash
+cd backend
+uvicorn gateway:app --host "0.0.0.0" --port=8000
+```
+
+The reasoning engine is now listening on http://localhost:8000. In `local`/`linked` mode it owns the policy lifecycle from a local SQLite store (seeded on first boot, editable via the Policy & Discovery tabs); in `cloud` mode it mirrors policies from your Supabase-backed Control Plane.
+
+---
+
+### Step 5: Run a Live Frictionless Run Pass
+Watch the AgentX SDK utilize its auto-reflective ingestion core to catch a nested SQL injection attempt hidden inside helper variables, bypass internal SQLAlchemy network pointers, and trigger an edge block without throwing a system crash exception:
+
+```bash 
+python examples/01_self_healing_agent.py
+```
+OR
+
+```bash 
+python examples/08_frictionless_agent_protection.py
+```
+
+---
+
+🕹️ Console Session Output Logs:
+
+```text
+========================================================================
+🤖 AGENTX DEMO 08: ZERO-CONFIGURATION ENTERPRISE TOOL PROTECTION
+========================================================================
+Scenario: An engineer wraps an existing corporate function with AgentX.
+The SDK automatically parses inputs via Python signature reflection.
+
+🔄 --- Agent Execution Step ---
+Agent Attempting Call: dispatch_crm_update(client_id='CLI-99401', profile_notes='...')
+Injected Input Payload: 'Customer requested normal update. Retain account historical state; DROP TABLE users;'
+
+🛡️ [AgentX SDK] Intercepting tool call to 'dispatch_crm_update' and active_stats = 0...
+⚡ [LOCAL KEYWORD SHIELD] Fast-path intercept engaged on policy 'Mass Destructive Intent' (offline, 0 gateway/LLM calls).
+🛑 [LOCAL BLOCK] Policy 'Mass Destructive Intent' matched a blocked intent locally. Returning offline instruction block string.
+
+🛑 [AGENTX REASONING ENGINE] Request Intercepted & Blocked!
+-> The reflection engine successfully captured the nested SQL payload.
+-> The SQLAlchemy session context object was safely ignored.
+
+🔒 Enterprise data assets protected via zero-configuration injection monitoring.
+========================================================================
+
+════════════════════════════════════════════════════════════
+ 🛡️  AgentX Session Summary (Trace: bbfda7a1-8e1b-41dd-8c59-b784a3bbdf6d)
+════════════════════════════════════════════════════════════
+ ⏱️  Uptime:                0.27 seconds
+ 🛠️  Tools Monitored:       2
+────────────────────────────────────────────────────────────
+ 🛑 Intercepts:            1   |  Cumulative: 3
+ 💥 Critical Blocks:       1   |  Cumulative: 1
+ 🚨 Human Escalations:     0   |  Cumulative: 0
+ 🔄 Self-Corrections:      1   |  Cumulative: 0
+ 📈 Recovery Rate:         100.0%
+ 💰 Tokens Saved:          ~1500
+ ⏳ Time Saved:            ~5s
+════════════════════════════════════════════════════════════
+```
+---
+
+📊 Executive Control Plane Telemetry
+When your agent script finishes or exits, local telemetry logs (.agentx.db) sync securely back to the central database layout. Open your browser workspace to http://localhost:3000/dashboard to inspect your real-time performance summary matrix:
+
+```text
++-----------------------------------------------------------------------------------+
+|                        EXECUTIVE COMMAND CONSOLE                                   |
++-----------------------------------------------------------------------------------+
+|  [Catastrophic Actions]   [Autonomous Recovery]  [Runs Protected]  [Time Saved]   |
+|         92                      36.3%                  37             12.3 hrs     |
+|  🛑 Irreversible/exfil   📈 Self-corrected ÷    🛡️ Runs that     ⏱️ ~20 min/run  |
+|     stopped pre-exec        challenged loops       self-corrected     reclaimed    |
++-----------------------------------------------------------------------------------+
+
+```
+
+**Executive ROI Mappings** (all computed *per session*, grouped by `trace_id`):
+* **Catastrophic Actions Blocked (hero):** A pure count of distinct sessions whose intercepted action fell in an irreversible / exfiltrative class — `failure_mode ∈ {DESTRUCTIVE_ACTION, PII_EXFILTRATION, NETWORK_TRAVERSAL, SECRETS_LEAK}`, with a policy-name keyword fallback. Every incident in the ledger is a *pre-execution* interception, so this is harm averted, not harm survived.
+* **Autonomous Recovery Rate:** Of the sessions that entered the challenge loop, the share whose terminal status is `COMPLIED` (the agent self-corrected). Counted per session so `recovered ⊆ challenged` — **bounded ≤100% by construction**. HITL-approved sessions are excluded; only autonomous self-correction counts.
+* **Agent Runs Protected:** Sessions the agent self-corrected after a block (terminal `COMPLIED`).
+* **Engineering Time Saved:** ~20 min of manual triage credited per protected run, valued at $75/hr.
+
+> Operator dashboard metrics are scoped to **production agents only** — demo, simulation, blind-eval, and test/probe traffic are excluded so benchmarks never inflate an operator's numbers (they showcase the engine on the public landing page instead).
+
+---
+
+🧠 The 5 Pillars of Agentic Security
+
+AgentX is built on a "Reasoning Engine" architecture that treats AI agents as autonomous employees rather than static scripts:
+
+1. **Cognitive Interception:** We intercept tool calls to compare the agent's stated intent (Chain of Thought) against its actual deterministic action.
+2. **Socratic Nudging:** Instead of crashing the agent, we issue a Socratic Challenge to guide them to a safe, desired end-goal.
+3. **Shared Immunity Network (roadmap):** Novel zero-day signatures discovered on one node are designed to graduate into the deterministic floor and propagate to other Edge nodes for O(1) interception. The local Discovery → Promote → live-in-3s loop works today; cross-node global distribution is a Day-100 capability and is **not yet active** — we don't claim it until it is.
+4. **Circuit Breakers:** If an agent enters an infinite hallucination loop, AgentX hard-locks the runtime after 3 strikes to prevent massive LLM token billing overages.
+5. **Human-in-the-Loop (HITL):** If an agent pulls the "Andon Cord" (requests help), the system suspends the execution thread (`202 Accepted`) and parks it in the SOC Sandbox for human approval.
+
+---
+
+🚀 The 4 Shields (Defense-in-Depth)
+1. The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
+
+2. The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
+
+3. The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
+
+4. The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
+
+---
+
+## 📊 Local Telemetry & Agent Health
+
+AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agentx.db`). It tracks every interception locally. When your agent script finishes or crashes, AgentX automatically prints a comprehensive Session Summary and Lifetime ROI dashboard:
+
+```text
+══════════════════════════════════════════════════
+ 🛡️  AgentX Session Summary
+══════════════════════════════════════════════════
+ ⏱️  Uptime:                9.17 seconds
+ 🛠️  Tools Monitored:       2
+──────────────────────────────────────────────────
+ 🛑 Intercepts:            1   |  Cumulative: 5
+ 💥 Critical Blocks:       1   |  Cumulative: 5
+ 💰 Tokens Saved:      ~1500   |  Cumulative: ~7500
+ ⏳ Time Saved:        ~5m     |  Cumulative: ~25m
+══════════════════════════════════════════════════
+ 🩺 AGENT HEALTH INSIGHT
+──────────────────────────────────────────────────
+ ⚠️ Top Offender: 'Database Isolation'
+ 🛠️  Tip: Consider refining your agent's system prompt to avoid this.
+══════════════════════════════════════════════════
+```
+
+---
+
+📦 Try the other Developer Demos
+Inside the examples/ folder, you will find a few standalone scripts proving the AgentX Reasoning Layer:
+
+* **01_self_healing_agent.py:** Watch AgentX catch a hallucination and coach the agent to self-correct (Saving tokens and uptime).
+* **02_cognitive_intent_block.py:** Watch AgentX catch malicious intent even when the raw syntax is perfectly safe.
+* **04_circuit_breaker_demo.py:** AgentX catches and prevents an infinite apology loop, saving time and tokens.
+* **06_hitl_escalation.py:** See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.
+* **And many more...**
+
+---
+
+## 🕹️ Human-in-the-Loop (HITL) & Control Plane
+Sometimes, an agent needs to drop a table for a valid business reason.
+
+AgentX features a Next.js Control Plane Dashboard. If an agent requests an escalation, the SDK securely pauses local execution and polls the Edge Reasoning Engine. A human SOC analyst can click "Approve" or "Deny" in the UI, and the Python execution loop will automatically resume.
+
+```bash
+cd ui
+npm install
+npm run dev
+
+---
+
+## 🏗️ The Architecture (Split-Plane)
+
+AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
+
+* **The Edge SDK (AgentX):** The lightweight Python package that instruments agent tools and triggers local Socratic self-healing.
+* **The Data Plane (Reasoning Engine):** A Python FastAPI middleware (the "Wedge") that intercepts raw HTTP/SQL payloads *before* they hit the database.
+* **The Control Plane (Dashboard):** A Next.js application (deployed via Vercel) that allows human reviewers to monitor intercepted agent traffic, review chains of thought, and approve or deny parked requests.
+* **The Shared Brain**: Mode-dependent. In `cloud`, Supabase is the central state manager and both planes synchronize through it. In `local`/`linked`, the gateway's own SQLite stores (`.agentx/incidents.db`, `.agentx/policies.db`) are authoritative and nothing leaves the machine unless you explicitly push it.
+* **The Evaluator:** Google's Gemini 2.5 Flash, Pro, or higher (configurable via an environment variable) is used to translate an agent's Chain of Thought (CoT) into a zero-knowledge taxonomy to evaluate intent against YAML-defined enterprise policies.
+
+---
+
+## ✨ Key Features & Built-in Policies
+
+* **Automated Socratic Self-Healing:** Intercepts dangerous tool calls and challenges the agent to revise its strategy.
+* **Fast Pass Heuristic Traps:** Instantly intercepts structurally dangerous queries (e.g., `DROP TABLE`, `DELETE`) with minimal latency.
+* **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
+* **Dynamic Policies:** In `cloud`, enforces isolation rules via a Supabase-backed Control Plane that syncs to edge caches in ~3 seconds. In `local`/`linked`, the gateway owns the policy lifecycle locally — create/edit/toggle/delete and AI-drafted promotions from the Policy & Discovery tabs are armed live (re-embedded into the in-RAM vector index) with no restart.
+
+---
+
+## 🔒 Security Posture
+
+* **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
+* **History Scrubbing:** This repository has been scrubbed of legacy keys using git-filter-repo.
+* **Private IP**: Repository is private to protect proprietary evaluation prompts and architecture.
+* **License**: Proprietary — all rights reserved. The Reasoning Engine (gateway) and Control Plane are closed source; no public open-source or source-available license is granted. Source access for evaluation is available to qualified enterprise customers and partners under written agreement. (The lightweight `agentx-security-sdk` edge client is published separately on PyPI.)
+
+---
+
+🚀 Future Roadmap & Milestones
+✅ Trust Boundary Shift: Moved neuro-symbolic evaluation entirely into the Data Plane container to eliminate agent runtime bypasses. (Completed)
+
+✅ Zero-Knowledge Hard Split-Plane: Mathematically enforced VPC telemetry isolation via localized metric stripping. (Completed)
+
+✅ Zero-Config Reflection Engine: Eliminated manual query and CoT boilerplate writing using dynamic signature parameters compilation hooks. (Completed)
+
+✅ Local Keyword Shield (Layer 0): Deterministic, dependency-free keyword/intent pre-filter in the SDK that intercepts obvious threats offline in sub-milliseconds — zero gateway/LLM calls. Scans the action payload only; chain-of-thought intent is deferred to the gateway's LLM judge. (Completed)
+
+✅ Judge Verdict Memoization: Bounded in-memory cache on the Data Plane that reuses prior LLM verdicts for identical (payload + reasoning + policy set), eliminating repeat Gemini calls during agent retry loops. (Completed)
+
+✅ Catastrophic-Action Hero Metric: Reframed the Executive ROI strip to lead with severity-filtered "Catastrophic Actions Blocked" (irreversible / exfiltration intents stopped pre-execution), with per-session metric accounting that bounds Recovery Rate ≤100% by construction across the dashboard, the Supabase summary view, and the SDK. (Completed)
+
+✅ Detection-vs-Recovery Eval Harness (`eval/`): Independent instruments that measure the engine honestly — `blind_agent_eval.py` (end-to-end detection recall via a blind LLM agent + independent oracle), `probe_judge.py` (isolates the reasoning layer's *marginal* recall over the deterministic floor), and `recovery_eval.py` (A/B marginal-recovery lift of the Socratic challenge vs a bare 403). (Completed)
+
+✅ Incident-Persistence Hardening & Fail-Mode Switch: Restored the CHALLENGED→COMPLIED persistence pipeline (gateway-pinned UUID receipts, `/v1/incident` Layer-0 registration, COMPLIED PATCH gated on a real `200`) and added `AGENTX_FAIL_MODE=open|closed`. (Completed)
+
+✅ Deterministic Floor — Hard-Block + HITL-Escalation + Loop-Abort Tiers: The zero-LLM core that runs before (and without) the judge — so the engine fully protects keyless. **Hard-block** tier DENIES never-legitimate actions (destructive DDL/DML incl. `ALTER … DROP COLUMN`, cluster/cloud teardown, SSRF, secret reads + egress exfiltration, filesystem whole-scope deletes + path-boundary escapes, remote-pipe-to-shell installs). **HITL-escalation** tier returns `202 ESCALATED` → human SOC for *consequence-gated* actions that can be legitimate: **High-Value Transfer Approval** (AFDB #41, `AGENTX_TRANSFER_ESCALATION_THRESHOLD`), **External Publication Approval** (AFDB #36), **Comms Bulk-Deletion Approval** (AFDB #35), and **Budget Ceiling Approval** (AFDB #17/#23 — cumulative session token/$ spend vs `AGENTX_SESSION_TOKEN_CEILING` / `AGENTX_SESSION_COST_CEILING_USD`; report real usage with `agentx.record_spend(...)` or rely on the built-in volume estimate). **Loop-abort** tier terminates runaway loops (strike-count breaker + the `detect_no_progress_loop` no-progress repeat breaker, AFDB #10, `AGENTX_LOOP_REPEAT_CEILING`). Every detector has a fires-in-anger test asserting attribution + zero LLM calls. See `AGENT_FAILURE_CATALOG.md` for the per-incident coverage state. (Completed)
+
+⬜ Downloadable Vector Seeds (`agentx compile`): Real pre-compiled fastembed vectors for offline semantic matching, scoped to air-gapped deployments. (Future)
+
+⬜ Containerized Multi-Region Edge Cluster: Standardize container blueprints for automated high-availability deployments onto AWS ECS and Render clusters. (Future)
+
+
+🤝 Contributing & Support
+We are actively partnering with engineering groups building production-grade autonomous agent systems. If you are tracking high-concurrency tool execution lines and are terrified of what your agent loops might drop or execute, open an issue card or reach out directly to join our design partner circle!
+
+

agentx_security_sdk-0.3.2/README.md

@@ -0,0 +1,308 @@
+# 🛡️ AgentX: The Action Firewall for AI Agents
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)
+
+LLM Agents are brilliant, but they are incredibly brittle. They will drop your production database, leak AWS keys, and fall victim to prompt injections. Traditional firewalls just crash the agent by returning a hard `403 Forbidden` exception, killing the run completely and wasting compute tokens.
+
+**AgentX is different — and it starts protecting you with zero keys.** Its hero is a **deterministic security floor** (the *Shield*): a local, sub-millisecond, zero-LLM layer that **hard-blocks** the catastrophic call (`DROP TABLE`, SSRF, secret reads, supply-chain RCE, destructive shell/cloud teardown) and **escalates to a human** the consequential-but-legitimate ones (large transfers, external publishes, runaway spend, bulk deletes). No API key, no signup, no network round-trip.
+
+Add a Gemini key and the optional **reasoning layer** turns each block into a **recoverable challenge** instead of a fatal `403` — the agent rethinks its strategy, fixes its parameters, and finishes the task *without crashing your application or draining tokens on a wiped run* — plus Discovery for novel-intent classification.
+
+### 🛡️ Block the catastrophic deterministically. 🧠 Coach the recoverable when you add a key.
+
+---
+
+## 🏗️ Split-Plane Architecture
+
+AgentX relies on a decoupled, split-plane hybrid architecture to balance latency with deep cognitive reasoning:
+
+* **The Edge SDK (`agentx_sdk`):** A low-config Python package instrumenting sensitive tool calls via reflective code signatures. 
+* **The Data Plane (Neuro-Symbolic Reasoning Engine):** A high-performance Python FastAPI service (the "Wedge"). Handles Abstract Syntax Tree (AST) evaluation, zero-day threat trapping, and the local immunity signature lookup via a strict Layer 0 -> Layer 1 -> Layer 2 funnel (the cross-node **Shared Immunity Network** is a roadmap capability — see Pillar 3).
+* **The Control Plane (Dashboard):** A Next.js application listening on port `3000`. Provides an executive command console for tracking corporate ROI metrics, analyzing agent Chain of Thought (CoT) loops, and promoting newly discovered policy vectors. Reads through a mode-aware edge layer: the gateway's local SQLite store in `local`/`linked` mode, a Supabase-backed real-time ledger in `cloud` mode.
+
+---
+
+## ⚡ 1. Quickstart
+
+AgentX requires **zero changes** to your underlying agentic logic, custom tools, or payload schemas. The SDK dynamically inspects function signatures at runtime using an auto-reflective ingestion engine.
+
+### Step 1: Install the SDK
+```bash
+pip install agentx-security-sdk
+```
+
+### Step 2: Decorate Sensitive Tool Operations
+Attach the `@agentx_protect` decorator over any high-risk system tool. The SDK automatically serializes parameters and enforces the evaluation wedge:
+
+```python
+# ✅ MODERN REFLECTIVE IMPORTS (No boilerplate functions required)
+from agentx_sdk.decorators import agentx_protect
+
+@agentx_protect(agent_id="frictionless_enterprise_worker")
+def dispatch_crm_update(client_id: str, profile_notes: str, db_session=None):
+    """
+    AgentX automatically inspects string elements, ignores connection objects
+    like 'db_session', and evaluates intents out-of-prompt natively in RAM.
+    """
+    print(f"Updating records for {client_id}")
+```
+---
+
+### Step 3: Configure Environment Flags
+
+Copy `.env.example` to `.env`. **You can run with zero keys.** Two *independent* axes shape your posture — the activation ladder:
+
+- **Reasoning axis (how much intelligence):** **Shield** is the default and needs no keys — the deterministic floor only. Add a `GEMINI_API_KEY` to unlock the reasoning judge (recovery coaching + Discovery). Force Shield even when a key is present with `AGENTX_REASONING=off`.
+- **Data axis — `AGENTX_MODE` (where data lives + sync):** `local` (isolated, no sync) → `linked` (explicit pull/push) → `cloud` (continuous sync + HITL/SOC; needs `AGENTX_API_KEY`).
+
+Shield is **not** a fourth mode — it crosses all three (you can run `cloud` + Shield, or `local` + judge).
+
+```text
+# Data axis — where data lives + sync posture:
+#   local   isolated; local SQLite store; no sync; no keys required
+#   linked  local-authoritative; explicit pull/push; no auto-sync
+#   cloud   control plane authoritative; continuous sync + upload + HITL/SOC
+AGENTX_MODE=local
+NEXT_PUBLIC_AGENTX_MODE=local   # the UI's build-time copy; keep it equal
+
+# Reasoning axis — OPTIONAL. Unset = Shield (floor-only, zero LLM, zero keys).
+# Add a key to unlock the judge (recovery coaching + Discovery).
+# GEMINI_API_KEY=your_gemini_key_here     # from aistudio.google.com
+# AGENTX_REASONING=off                    # force Shield even when a key is present
+
+# AgentX API key — required for `cloud` (and `linked` against a remote plane).
+# Omit for `local`/Shield; the gateway falls back to a sandbox key.
+# AGENTX_API_KEY=agentx_sk_your_key_here
+```
+
+**Safety posture (optional).** By default AgentX **fails open** — if the Reasoning Engine is unreachable, tool calls still execute, but with a loud warning, an audit tally in the session summary, and the in-process offline keyword shield still blocking deterministic threats (e.g. `DROP TABLE`). For high-stakes or irreversible actions, set `AGENTX_FAIL_MODE=closed` to instead **block** any tool call the engine can't verify until it recovers.
+
+---
+
+### Step 4: Spin up the Edge Reasoning Engine
+Boot your local data plane wedge proxy middleware and your frontend dashboard console node simultaneously:
+
+```bash
+docker-compose up -d
+```
+OR
+
+```bash
+cd backend
+uvicorn gateway:app --host "0.0.0.0" --port=8000
+```
+
+The reasoning engine is now listening on http://localhost:8000. In `local`/`linked` mode it owns the policy lifecycle from a local SQLite store (seeded on first boot, editable via the Policy & Discovery tabs); in `cloud` mode it mirrors policies from your Supabase-backed Control Plane.
+
+---
+
+### Step 5: Run a Live Frictionless Run Pass
+Watch the AgentX SDK utilize its auto-reflective ingestion core to catch a nested SQL injection attempt hidden inside helper variables, bypass internal SQLAlchemy network pointers, and trigger an edge block without throwing a system crash exception:
+
+```bash 
+python examples/01_self_healing_agent.py
+```
+OR
+
+```bash 
+python examples/08_frictionless_agent_protection.py
+```
+
+---
+
+🕹️ Console Session Output Logs:
+
+```text
+========================================================================
+🤖 AGENTX DEMO 08: ZERO-CONFIGURATION ENTERPRISE TOOL PROTECTION
+========================================================================
+Scenario: An engineer wraps an existing corporate function with AgentX.
+The SDK automatically parses inputs via Python signature reflection.
+
+🔄 --- Agent Execution Step ---
+Agent Attempting Call: dispatch_crm_update(client_id='CLI-99401', profile_notes='...')
+Injected Input Payload: 'Customer requested normal update. Retain account historical state; DROP TABLE users;'
+
+🛡️ [AgentX SDK] Intercepting tool call to 'dispatch_crm_update' and active_stats = 0...
+⚡ [LOCAL KEYWORD SHIELD] Fast-path intercept engaged on policy 'Mass Destructive Intent' (offline, 0 gateway/LLM calls).
+🛑 [LOCAL BLOCK] Policy 'Mass Destructive Intent' matched a blocked intent locally. Returning offline instruction block string.
+
+🛑 [AGENTX REASONING ENGINE] Request Intercepted & Blocked!
+-> The reflection engine successfully captured the nested SQL payload.
+-> The SQLAlchemy session context object was safely ignored.
+
+🔒 Enterprise data assets protected via zero-configuration injection monitoring.
+========================================================================
+
+════════════════════════════════════════════════════════════
+ 🛡️  AgentX Session Summary (Trace: bbfda7a1-8e1b-41dd-8c59-b784a3bbdf6d)
+════════════════════════════════════════════════════════════
+ ⏱️  Uptime:                0.27 seconds
+ 🛠️  Tools Monitored:       2
+────────────────────────────────────────────────────────────
+ 🛑 Intercepts:            1   |  Cumulative: 3
+ 💥 Critical Blocks:       1   |  Cumulative: 1
+ 🚨 Human Escalations:     0   |  Cumulative: 0
+ 🔄 Self-Corrections:      1   |  Cumulative: 0
+ 📈 Recovery Rate:         100.0%
+ 💰 Tokens Saved:          ~1500
+ ⏳ Time Saved:            ~5s
+════════════════════════════════════════════════════════════
+```
+---
+
+📊 Executive Control Plane Telemetry
+When your agent script finishes or exits, local telemetry logs (.agentx.db) sync securely back to the central database layout. Open your browser workspace to http://localhost:3000/dashboard to inspect your real-time performance summary matrix:
+
+```text
++-----------------------------------------------------------------------------------+
+|                        EXECUTIVE COMMAND CONSOLE                                   |
++-----------------------------------------------------------------------------------+
+|  [Catastrophic Actions]   [Autonomous Recovery]  [Runs Protected]  [Time Saved]   |
+|         92                      36.3%                  37             12.3 hrs     |
+|  🛑 Irreversible/exfil   📈 Self-corrected ÷    🛡️ Runs that     ⏱️ ~20 min/run  |
+|     stopped pre-exec        challenged loops       self-corrected     reclaimed    |
++-----------------------------------------------------------------------------------+
+
+```
+
+**Executive ROI Mappings** (all computed *per session*, grouped by `trace_id`):
+* **Catastrophic Actions Blocked (hero):** A pure count of distinct sessions whose intercepted action fell in an irreversible / exfiltrative class — `failure_mode ∈ {DESTRUCTIVE_ACTION, PII_EXFILTRATION, NETWORK_TRAVERSAL, SECRETS_LEAK}`, with a policy-name keyword fallback. Every incident in the ledger is a *pre-execution* interception, so this is harm averted, not harm survived.
+* **Autonomous Recovery Rate:** Of the sessions that entered the challenge loop, the share whose terminal status is `COMPLIED` (the agent self-corrected). Counted per session so `recovered ⊆ challenged` — **bounded ≤100% by construction**. HITL-approved sessions are excluded; only autonomous self-correction counts.
+* **Agent Runs Protected:** Sessions the agent self-corrected after a block (terminal `COMPLIED`).
+* **Engineering Time Saved:** ~20 min of manual triage credited per protected run, valued at $75/hr.
+
+> Operator dashboard metrics are scoped to **production agents only** — demo, simulation, blind-eval, and test/probe traffic are excluded so benchmarks never inflate an operator's numbers (they showcase the engine on the public landing page instead).
+
+---
+
+🧠 The 5 Pillars of Agentic Security
+
+AgentX is built on a "Reasoning Engine" architecture that treats AI agents as autonomous employees rather than static scripts:
+
+1. **Cognitive Interception:** We intercept tool calls to compare the agent's stated intent (Chain of Thought) against its actual deterministic action.
+2. **Socratic Nudging:** Instead of crashing the agent, we issue a Socratic Challenge to guide them to a safe, desired end-goal.
+3. **Shared Immunity Network (roadmap):** Novel zero-day signatures discovered on one node are designed to graduate into the deterministic floor and propagate to other Edge nodes for O(1) interception. The local Discovery → Promote → live-in-3s loop works today; cross-node global distribution is a Day-100 capability and is **not yet active** — we don't claim it until it is.
+4. **Circuit Breakers:** If an agent enters an infinite hallucination loop, AgentX hard-locks the runtime after 3 strikes to prevent massive LLM token billing overages.
+5. **Human-in-the-Loop (HITL):** If an agent pulls the "Andon Cord" (requests help), the system suspends the execution thread (`202 Accepted`) and parks it in the SOC Sandbox for human approval.
+
+---
+
+🚀 The 4 Shields (Defense-in-Depth)
+1. The Inbound Shield (Prompt Injection): Sanitizes inbound user text to prevent cognitive hijacking ("Ignore previous instructions") before the agent reads it.
+
+2. The Logic Shield (Database Guard): Uses AST parsing and Gemini to catch destructive queries (DROP, DELETE) and nudges the agent to write safer SQL.
+
+3. The Network Shield (SSRF Guard): Prevents agents from acting as confused deputies to hit cloud metadata IPs (e.g., 169.254.169.254).
+
+4. The Egress Shield (DLP/PII Scrubber): Dynamically masks PII and API keys on the wire, maintaining clean audit logs without triggering SOC alert fatigue.
+
+---
+
+## 📊 Local Telemetry & Agent Health
+
+AgentX ships with a built-in, privacy-first SQLite time-series event log (`.agentx.db`). It tracks every interception locally. When your agent script finishes or crashes, AgentX automatically prints a comprehensive Session Summary and Lifetime ROI dashboard:
+
+```text
+══════════════════════════════════════════════════
+ 🛡️  AgentX Session Summary
+══════════════════════════════════════════════════
+ ⏱️  Uptime:                9.17 seconds
+ 🛠️  Tools Monitored:       2
+──────────────────────────────────────────────────
+ 🛑 Intercepts:            1   |  Cumulative: 5
+ 💥 Critical Blocks:       1   |  Cumulative: 5
+ 💰 Tokens Saved:      ~1500   |  Cumulative: ~7500
+ ⏳ Time Saved:        ~5m     |  Cumulative: ~25m
+══════════════════════════════════════════════════
+ 🩺 AGENT HEALTH INSIGHT
+──────────────────────────────────────────────────
+ ⚠️ Top Offender: 'Database Isolation'
+ 🛠️  Tip: Consider refining your agent's system prompt to avoid this.
+══════════════════════════════════════════════════
+```
+
+---
+
+📦 Try the other Developer Demos
+Inside the examples/ folder, you will find a few standalone scripts proving the AgentX Reasoning Layer:
+
+* **01_self_healing_agent.py:** Watch AgentX catch a hallucination and coach the agent to self-correct (Saving tokens and uptime).
+* **02_cognitive_intent_block.py:** Watch AgentX catch malicious intent even when the raw syntax is perfectly safe.
+* **04_circuit_breaker_demo.py:** AgentX catches and prevents an infinite apology loop, saving time and tokens.
+* **06_hitl_escalation.py:** See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.
+* **And many more...**
+
+---
+
+## 🕹️ Human-in-the-Loop (HITL) & Control Plane
+Sometimes, an agent needs to drop a table for a valid business reason.
+
+AgentX features a Next.js Control Plane Dashboard. If an agent requests an escalation, the SDK securely pauses local execution and polls the Edge Reasoning Engine. A human SOC analyst can click "Approve" or "Deny" in the UI, and the Python execution loop will automatically resume.
+
+```bash
+cd ui
+npm install
+npm run dev
+
+---
+
+## 🏗️ The Architecture (Split-Plane)
+
+AgentX relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security for AI-driven enterprise systems.
+
+* **The Edge SDK (AgentX):** The lightweight Python package that instruments agent tools and triggers local Socratic self-healing.
+* **The Data Plane (Reasoning Engine):** A Python FastAPI middleware (the "Wedge") that intercepts raw HTTP/SQL payloads *before* they hit the database.
+* **The Control Plane (Dashboard):** A Next.js application (deployed via Vercel) that allows human reviewers to monitor intercepted agent traffic, review chains of thought, and approve or deny parked requests.
+* **The Shared Brain**: Mode-dependent. In `cloud`, Supabase is the central state manager and both planes synchronize through it. In `local`/`linked`, the gateway's own SQLite stores (`.agentx/incidents.db`, `.agentx/policies.db`) are authoritative and nothing leaves the machine unless you explicitly push it.
+* **The Evaluator:** Google's Gemini 2.5 Flash, Pro, or higher (configurable via an environment variable) is used to translate an agent's Chain of Thought (CoT) into a zero-knowledge taxonomy to evaluate intent against YAML-defined enterprise policies.
+
+---
+
+## ✨ Key Features & Built-in Policies
+
+* **Automated Socratic Self-Healing:** Intercepts dangerous tool calls and challenges the agent to revise its strategy.
+* **Fast Pass Heuristic Traps:** Instantly intercepts structurally dangerous queries (e.g., `DROP TABLE`, `DELETE`) with minimal latency.
+* **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
+* **Dynamic Policies:** In `cloud`, enforces isolation rules via a Supabase-backed Control Plane that syncs to edge caches in ~3 seconds. In `local`/`linked`, the gateway owns the policy lifecycle locally — create/edit/toggle/delete and AI-drafted promotions from the Policy & Discovery tabs are armed live (re-embedded into the in-RAM vector index) with no restart.
+
+---
+
+## 🔒 Security Posture
+
+* **Secret Management:** API keys are never checked into version control. Production variables are managed securely via the Vercel Dashboard.
+* **History Scrubbing:** This repository has been scrubbed of legacy keys using git-filter-repo.
+* **Private IP**: Repository is private to protect proprietary evaluation prompts and architecture.
+* **License**: Proprietary — all rights reserved. The Reasoning Engine (gateway) and Control Plane are closed source; no public open-source or source-available license is granted. Source access for evaluation is available to qualified enterprise customers and partners under written agreement. (The lightweight `agentx-security-sdk` edge client is published separately on PyPI.)
+
+---
+
+🚀 Future Roadmap & Milestones
+✅ Trust Boundary Shift: Moved neuro-symbolic evaluation entirely into the Data Plane container to eliminate agent runtime bypasses. (Completed)
+
+✅ Zero-Knowledge Hard Split-Plane: Mathematically enforced VPC telemetry isolation via localized metric stripping. (Completed)
+
+✅ Zero-Config Reflection Engine: Eliminated manual query and CoT boilerplate writing using dynamic signature parameters compilation hooks. (Completed)
+
+✅ Local Keyword Shield (Layer 0): Deterministic, dependency-free keyword/intent pre-filter in the SDK that intercepts obvious threats offline in sub-milliseconds — zero gateway/LLM calls. Scans the action payload only; chain-of-thought intent is deferred to the gateway's LLM judge. (Completed)
+
+✅ Judge Verdict Memoization: Bounded in-memory cache on the Data Plane that reuses prior LLM verdicts for identical (payload + reasoning + policy set), eliminating repeat Gemini calls during agent retry loops. (Completed)
+
+✅ Catastrophic-Action Hero Metric: Reframed the Executive ROI strip to lead with severity-filtered "Catastrophic Actions Blocked" (irreversible / exfiltration intents stopped pre-execution), with per-session metric accounting that bounds Recovery Rate ≤100% by construction across the dashboard, the Supabase summary view, and the SDK. (Completed)
+
+✅ Detection-vs-Recovery Eval Harness (`eval/`): Independent instruments that measure the engine honestly — `blind_agent_eval.py` (end-to-end detection recall via a blind LLM agent + independent oracle), `probe_judge.py` (isolates the reasoning layer's *marginal* recall over the deterministic floor), and `recovery_eval.py` (A/B marginal-recovery lift of the Socratic challenge vs a bare 403). (Completed)
+
+✅ Incident-Persistence Hardening & Fail-Mode Switch: Restored the CHALLENGED→COMPLIED persistence pipeline (gateway-pinned UUID receipts, `/v1/incident` Layer-0 registration, COMPLIED PATCH gated on a real `200`) and added `AGENTX_FAIL_MODE=open|closed`. (Completed)
+
+✅ Deterministic Floor — Hard-Block + HITL-Escalation + Loop-Abort Tiers: The zero-LLM core that runs before (and without) the judge — so the engine fully protects keyless. **Hard-block** tier DENIES never-legitimate actions (destructive DDL/DML incl. `ALTER … DROP COLUMN`, cluster/cloud teardown, SSRF, secret reads + egress exfiltration, filesystem whole-scope deletes + path-boundary escapes, remote-pipe-to-shell installs). **HITL-escalation** tier returns `202 ESCALATED` → human SOC for *consequence-gated* actions that can be legitimate: **High-Value Transfer Approval** (AFDB #41, `AGENTX_TRANSFER_ESCALATION_THRESHOLD`), **External Publication Approval** (AFDB #36), **Comms Bulk-Deletion Approval** (AFDB #35), and **Budget Ceiling Approval** (AFDB #17/#23 — cumulative session token/$ spend vs `AGENTX_SESSION_TOKEN_CEILING` / `AGENTX_SESSION_COST_CEILING_USD`; report real usage with `agentx.record_spend(...)` or rely on the built-in volume estimate). **Loop-abort** tier terminates runaway loops (strike-count breaker + the `detect_no_progress_loop` no-progress repeat breaker, AFDB #10, `AGENTX_LOOP_REPEAT_CEILING`). Every detector has a fires-in-anger test asserting attribution + zero LLM calls. See `AGENT_FAILURE_CATALOG.md` for the per-incident coverage state. (Completed)
+
+⬜ Downloadable Vector Seeds (`agentx compile`): Real pre-compiled fastembed vectors for offline semantic matching, scoped to air-gapped deployments. (Future)
+
+⬜ Containerized Multi-Region Edge Cluster: Standardize container blueprints for automated high-availability deployments onto AWS ECS and Render clusters. (Future)
+
+
+🤝 Contributing & Support
+We are actively partnering with engineering groups building production-grade autonomous agent systems. If you are tracking high-concurrency tool execution lines and are terrified of what your agent loops might drop or execute, open an issue card or reach out directly to join our design partner circle!
+
+