Metadata-Version: 2.4
Name: agentx-security-sdk
Version: 0.1.0
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

# Semantic Gateway 🛡️

Semantic Gateway 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, enabling a safe "human-in-the-loop" environment for AI-driven enterprise systems.

## 🚀 The Architecture (Split-Plane)

Semantic Gateway relies on a decoupled, hybrid-cloud architecture to ensure maximum performance and security.

* **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 Data Plane (Semantic Firewall):** A Python FastAPI middleware (the "Wedge") that intercepts raw HTTP/SQL payloads *before* they hit the database.
* **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

* **Fast Pass Heuristic Traps:** Instantly intercepts structurally dangerous queries (e.g., `DROP TABLE`, `DELETE`) with minimal latency.
* **Asynchronous Polling Loop:** Employs a robust `428 Precondition Required` negotiation. Blocked agents are "parked," receiving a receipt ID, and asynchronously poll the gateway until a human resolves the incident.
* **Zero-Knowledge Intent Extraction:** Prevents malicious prompt injection by translating raw agent logic into a strict schema before policy evaluation.
* **Dynamic YAML Policies:** Easily define what specific frontend/backend intents should be blocked or isolated from destructive database writes.

## 🛠️ Getting Started

### 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 (Local)
Start the FastAPI server via Uvicorn. This acts as the Wedge intercepting traffic.


cd backend
pip install fastapi uvicorn requests pyyaml supabase pydantic google-genai python-dotenv
uvicorn main:app --reload

3. Run the Control Plane Dashboard (Vercel/Local)
Start your Next.js application to view the intercepted incidents.


cd ui
npm install
npm run dev

4. Run the Agent Simulation
Simulate a rogue agent attempting a destructive action (DROP TABLE). Watch the firewall intercept it and route it to your dashboard.

python backend/main.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.
