Metadata-Version: 2.4
Name: superagentx-policy-engine
Version: 0.1.0
Summary: An open-source Python framework leveraging efficient trie structures
Project-URL: Homepage, https://github.com/your-username/superagentx-policy-engine
Project-URL: Bug Tracker, https://github.com/your-username/superagentx-policy-engine/issues
Author-email: Prabhu Raghav <raghavprabhu06@gmail.com>
License: 
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: cedarpy>=4.8.4
Requires-Dist: cryptography>=48.0.0
Requires-Dist: litellm>=1.88.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# SuperAgentX Policy Engine

> Enterprise-grade AI Agent Governance Framework for Autonomous AI Systems

[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)]()
[![License](https://img.shields.io/badge/license-MIT-green.svg)]()
[![Async](https://img.shields.io/badge/async-native-orange.svg)]()

SuperAgentX Policy Engine is an AI Agent Governance Framework designed to secure, control, and govern autonomous AI systems.

Unlike traditional authorization frameworks, SuperAgentX Policy Engine understands:

- Agents
- Workflows
- LLMs
- Tools
- Memory
- Multi-Agent Systems
- Human Approvals
- AI Threats

---

# Why This Exists

Modern AI Agents can:

- Execute shell commands
- Access databases
- Call APIs
- Modify memory
- Spawn new agents
- Communicate with other agents
- Spend money through LLM usage
- Access enterprise systems

Traditional authorization systems were built for users and applications.

They were not built for:

```text
Agent -> Agent
Agent -> Tool
Agent -> LLM
Agent -> Memory
Agent -> Workflow
Agent -> Enterprise Systems
```

SuperAgentX Policy Engine introduces a governance layer between AI agents and execution.

---

# Architecture

```text
Agent
   │
   ▼

Governance Layer

   ├── Threat Detection
   ├── Rate Limiting
   ├── Quota Management
   ├── Policy Evaluation
   ├── Human Approval (HITL)
   ├── Cost Governance
   └── Audit Logging

   │
   ▼

Tool / LLM / Database / API
```

---

# Features

## Policy-Based Governance

IAM-style policies.

## Human-in-the-Loop (HITL)

Require approvals before risky actions.

## Threat Detection

Detect:

- Prompt Injection
- Jailbreak Attempts
- Data Exfiltration
- Credential Theft
- Agent Abuse
- Recursive Agent Attacks

## Cost Governance

Control AI spending.

## Tool Governance

Control access to tools.

## Memory Governance

Protect sensitive memory.

## Agent Governance

Control:

- agent:execute
- agent:spawn
- agent:communicate

## Audit Trail

Track every decision.

## Async First

Built for high-scale agent systems.

---

# Installation

```bash
pip install superagentx-policy-engine
```

---

# Quick Start

## Load Policy

```python
from superagentx_policy_engine.policy_engine import PolicyEngine
from superagentx_policy_engine.store.file_store import FilePolicyStore

engine = PolicyEngine()

policy = FilePolicyStore.load(
    "policies/allow_search.json"
)

await engine.add_policy_document(policy)
```

---

# Policy Format

```json
{
  "version": "2026-01-01",
  "statements": [
    {
      "sid": "AllowWebSearch",
      "effect": "Allow",
      "action": [
        "tool:execute"
      ],
      "resource": [
        "tool:web_search"
      ]
    }
  ]
}
```

---

# Effects

Supported effects:

```text
Allow
Deny
Approve
```

Priority:

```text
Deny
 >
Approve
 >
Allow
```

---

# Human Approval Example

```json
{
  "sid":"LargeSpendApproval",
  "effect":"Approve",
  "action":["llm:invoke"],
  "resource":["*"],
  "condition":{
    "NumericGreaterThan":{
      "context.custom.estimated_cost":100
    }
  },
  "approval":{
    "role":"finance_manager"
  }
}
```

---

# Tool Governance

Block dangerous tools.

```json
{
  "sid":"BlockShell",
  "effect":"Deny",
  "action":["tool:execute"],
  "resource":["tool:shell"]
}
```

---

# Memory Governance

```json
{
  "sid":"ProtectCustomerMemory",
  "effect":"Deny",
  "action":["memory:delete"],
  "resource":["memory:customer-*"]
}
```

---

# Agent Spawn Protection

```json
{
  "sid":"SpawnProtection",
  "effect":"Deny",
  "condition":{
    "NumericGreaterThan":{
      "context.custom.spawn_count":50
    }
  }
}
```

---

# Threat Detection

Built-in threat protection.

## Signature Detection

Detects known attacks.

## Rule Detection

Detects suspicious behavior.

## LLM Detection

Powered by LiteLLM.

Supported providers:

- OpenAI
- Claude
- Gemini
- Bedrock
- Azure OpenAI
- Ollama
- Groq
- DeepSeek

---

# Multi-Stage Threat Detection

```python
detector = EnsembleThreatDetector(
    detectors=[
        SignatureThreatDetector(),
        RuleThreatDetector(),
        LiteLLMThreatDetector(
            model="gemini/gemini-2.5-pro"
        )
    ]
)
```

Pipeline:

```text
Request
   │
   ▼

Signature Detector
   │
   ▼

Rule Detector
   │
   ▼

LLM Detector
   │
   ▼

Policy Engine
```

---

# Policy Hierarchy

```text
Global Policy
      │
      ▼
Workflow Policy
      │
      ▼
Agent Policy
      │
      ▼
Engine Policy
      │
      ▼
Handler Policy
```

---

# Multi-Agent Governance

Govern agent interactions.

```text
Research Agent
      │
      ▼
Fact Check Agent
      │
      ▼
Summary Agent
      │
      ▼
Report Agent
```

Policies can control:

```text
agent:execute
agent:spawn
agent:communicate
```

---

# SuperAgentX Integration

```text
AgentXPipe
     │
     ▼

workflow:start
     │
     ▼

agent:execute
     │
     ▼

engine:execute
     │
     ▼

tool:execute
```

Governance checks can happen at every stage.

---

# Use Cases

## AI Workforce Governance

Control autonomous teams.

## FinOps

Control AI spending.

## Production Change Management

Require approvals before production access.

## Secure Tool Usage

Restrict dangerous operations.

## Multi-Agent Security

Govern agent-to-agent interactions.

## Memory Protection

Prevent accidental deletion.

## Enterprise AI Governance

Apply policies consistently across all agents.

---

# Examples

```text
01_allow
02_deny_override
03_hitl_approval
04_tool_governance
05_cost_governance
06_spawn_protection
07_chain_depth_protection
08_memory_governance
09_threat_detection
10_budget_control
11_prod_database_approval
12_multi_agent_governance
13_showcase_demo
14_llm_threat_detection
15_multi_stage_threat_detection
```

---

# Roadmap

## Current

- Allow
- Deny
- Approve
- Conditions
- Threat Detection
- Rate Limiting
- Quotas
- Audit Logs
- LiteLLM Integration

## Upcoming

- Policy Registry
- Policy Versioning
- Policy Signing
- Workflow Policies
- Agent Policies
- Engine Policies
- Handler Policies
- ReBAC
- Cedar Compatibility

---

# Comparison

| Feature | SuperAgentX | OPA | Cedar |
|----------|------------|------|--------|
| Agent Governance | ✅ | ❌ | ❌ |
| HITL Approvals | ✅ | ❌ | ❌ |
| Threat Detection | ✅ | ❌ | ❌ |
| LLM Governance | ✅ | ❌ | ❌ |
| Cost Governance | ✅ | ❌ | ❌ |
| Multi-Agent Governance | ✅ | ❌ | ❌ |

---

# Contributing

Contributions are welcome.

Please open issues, discussions, and pull requests.

---

# License

SuperAgentX Policy Engine is released under the MIT License.


---

Built for the next generation of autonomous AI systems.
