Metadata-Version: 2.4
Name: agentx-security-sdk
Version: 0.2.1
Summary: The self-healing exception handler for autonomous AI agents.
Home-page: https://github.com/vdalal/semantic-gateway
Author: AgentX Team
Author-email: founders@agentx.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 Security SDK & Semantic Gateway 🛡️

AgentX is a production-grade security layer and semantic firewall designed specifically for autonomous AI agents. It intercepts, evaluates, and conditionally blocks agent-driven actions based on intent, policy violation, and neuro-symbolic evaluation.

Instead of failing silently or requiring immediate human intervention, the AgentX Edge SDK issues a **Socratic Challenge**, forcing the agent to reason about its actions and self-correct into a safe operation.

## 🚀 Quickstart (Agent Integration)

Install the SDK via PyPI:
```bash
pip install agentx-security-sdk
```

Wrap any sensitive tool or function with the `@agentx_protect` decorator. AgentX operates at the edge, adding zero latency to your cloud operations until an anomaly is detected.

```python
from agentx_sdk.decorators import agentx_protect

@agentx_protect(agent_id="agent_prod_01")
def execute_database_query(query: str):
    # Your database logic here
    return db.execute(query)

```

## 📊 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.
══════════════════════════════════════════════════

```

## 🏗️ 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 (Semantic Firewall):** 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:** Supabase acts as the central state manager. Both the Control Plane and Data Plane synchronize via Supabase, decoupling the network architecture and allowing asynchronous state polling.
* **The Evaluator:** Google's Gemini 2.5 Flash 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 YAML Policies:** Enforces isolation rules like "Mass Destructive Intent", "Database Isolation", "Network Sandbox (SSRF)", and "Secrets Exfiltration".

## 🛠️ Getting Started (Backend Deployment)

If you are deploying your own instance of the Semantic Gateway Control Plane:

### Prerequisites

* Python 3.10+
* Node.js 18+
* [Supabase](https://supabase.com) Account
* [Google AI Studio](https://aistudio.google.com/) API Key (Gemini)

### 1. Environment Variables

Create a `.env` file in the root directory. **Ensure this file is in your `.gitignore` to protect your IP and keys.**

```env
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_service_role_key
GEMINI_API_KEY=your_gemini_api_key

```

### 2. Run the Semantic Firewall (Dockerized)
The Data Plane (Wedge) is fully containerized for maximum reliability. Make sure your `.env` is configured in the root directory, then build and run the backend:

```bash
cd backend
docker build -t agentx-gateway .
docker run -p 8000:8000 --env-file ../.env agentx-gateway

```

The firewall is now intercepting traffic at http://localhost:8000

### 3. Run the Control Plane Dashboard (Vercel/Local)

Start your Next.js application to view the intercepted incidents.

```bash
cd ui
npm install
npm run dev

```
Your dashboard is now live at http://localhost:3000

### 4. Run the Agent Simulation

Simulate a rogue agent attempting a destructive action. Watch the firewall intercept it, issue a challenge, and route it to your dashboard.

```bash
python examples/simulate_agent_sdk.py

```

## 🔒 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.

## 📈 Roadmap

* **Trust Boundary Shift:** Move the neuro-symbolic evaluation entirely behind the Data Plane to prevent agent manipulation.
* **Dynamic Policy Engine:** Shift YAML configurations directly into Supabase for instant Control Plane sync.
* **Dockerization:** Containerize the Data Plane for deployment to AWS ECS / Render for persistent, low-latency edge interception.
* **Multi-Tenancy:** Implement Supabase Row Level Security (RLS) for multi-org deployments.

