argus-shield 0.1.0__tar.gz

argus_shield-0.1.0/.gitignore

@@ -0,0 +1,179 @@
+# ========== Python ==========
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.env.local
+.env.*.local
+*.env
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+*.log
+logs/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+
+# ========== Node.js / React (argus-dashboard) ==========
+
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Build outputs
+dist/
+dist-ssr/
+build/
+*.tsbuildinfo
+
+# Production
+.parcel-cache/
+.next/
+out/
+.nuxt/
+.cache/
+
+# Testing
+coverage/
+
+# Misc
+.DS_Store
+*.local
+
+# Environment variables
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Vite
+.vite/
+vite.config.ts.timestamp-*
+vite.config.ts.timestamp.*
+
+
+# ========== General / OS ==========
+
+# OS
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.swp
+*~
+
+# Archives
+*.zip
+*.tar.gz
+*.rar
+
+
+# ========== Project Specific ==========
+
+# Backend
+*.csv
+*.json
+!sample.json
+!argus-dashboard/vercel.json
+uploads/
+temp/
+
+
+# Sensitive files (should never be committed)
+*.pem
+*.key
+
+# ========== Keep These =========
+
+# Keep these files in git
+!requirements.txt
+!.env.example
+
+lobster-trap
+lobstertrap/.git/
+
+test_agent.py
+test_gemini.py

argus_shield-0.1.0/DOCUMENTATION.md

@@ -0,0 +1,278 @@
+# ARGUS Python SDK Developer Manual
+
+Welcome to the official developer documentation for the **ARGUS Python SDK** (`argus-sdk`). 
+
+ARGUS (**Agent Runtime Guardrail & Unauthorized-action Stopper**) is a real-time, active security guardrail for AI agents. Rather than classifying prompts or relying on fragile system instructions, ARGUS secures the **runtime execution boundary** by intercepting dangerous tool calls *before* they run.
+
+This guide covers everything you need to build secure, production-grade AI agents using the ARGUS ecosystem.
+
+---
+
+## Table of Contents
+1. [System Architecture](#system-architecture)
+2. [Getting Started E2E](#getting-started-e2e)
+3. [Core SDK Concepts](#core-sdk-concepts)
+4. [Vanilla Python Decorators](#vanilla-python-decorators)
+5. [Framework Integrations](#framework-integrations)
+   - [LangChain](#langchain)
+   - [PydanticAI](#pydanticai)
+   - [CrewAI / AutoGen](#crewai--autogen)
+6. [Security Paradigms](#security-paradigms)
+7. [API Reference](#api-reference)
+
+---
+
+## System Architecture
+
+ARGUS operates as a **Security Gateway Pattern**:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant App as Agent Application
+    participant SDK as ARGUS SDK (Client)
+    participant GW as ARGUS Gateway (Backend)
+    participant LLM as Model Provider (OpenAI/Gemini/Anthropic)
+    
+    App->>SDK: Establish argus.Session(user_prompt)
+    SDK->>GW: POST /api/intent/extract (prompt)
+    GW->>LLM: Analyze intent & compile Intent Manifest
+    LLM-->>GW: Return Manifest (Permissions Slip)
+    GW-->>SDK: Return Session ID + Manifest
+    
+    Note over App, SDK: Agent loop begins execution...
+    
+    App->>SDK: Invoke @argus.protect tool (params)
+    SDK->>GW: POST /api/evaluate (action, target, params)
+    Note over GW: Lobster Trap engine checks policy
+    
+    alt Action Authorized
+        GW-->>SDK: ALLOW
+        SDK-->>App: Permit execution of raw Python code
+    else Action Violates Intent
+        GW-->>SDK: QUARANTINE / DENY
+        Note over GW: Layer 3 generates explanation
+        SDK-->>App: Raise ArgusQuarantineException (Block!)
+    end
+```
+
+The **Gateway** manages heavy safety logic, model orchestrations, and telemetry. The **SDK** is a lightweight, zero-dependency client that developer-protects local execution blocks.
+
+---
+
+## Getting Started E2E
+
+Follow these steps to secure your first AI agent.
+
+### 1. Start the ARGUS Security Gateway
+Clone the central ARGUS repository and spin up the gateway server on your machine or private cloud.
+
+```bash
+# Clone and setup
+git clone https://github.com/tanishra/argus.git
+cd argus
+cp .env.example .env
+```
+
+Configure your gateway `.env` with your preferred LLM provider. ARGUS is completely model-agnostic thanks to LiteLLM:
+
+```ini
+# --- LLM API Keys ---
+OPENAI_API_KEY=sk-proj-xxxxxx...
+# GEMINI_API_KEY=AIzaSy...
+
+# --- Model Selection (LiteLLM Format) ---
+ARGUS_LLM_MODEL=openai/gpt-4o-mini
+ARGUS_PRO_MODEL=openai/gpt-4o
+```
+
+Start the gateway:
+```bash
+uv run uvicorn src.main:app --port 8000 --reload
+```
+
+### 2. Install the SDK in Your Project
+In your separate AI agent codebase, install the lightweight client:
+
+```bash
+pip install argus-sdk
+# or using uv
+uv add argus-sdk
+```
+
+Configure your environment to point to your self-hosted Gateway:
+
+```bash
+export ARGUS_BASE_URL="http://localhost:8000"
+export ARGUS_API_KEY="your-gateway-secret-key"
+```
+
+---
+
+## Core SDK Concepts
+
+ARGUS relies on two simple steps to enforce bulletproof guardrails:
+
+1. **The Session Context**: Wraps the agent's lifetime. It translates what the user *asked* into an immutable "Permission Slip" (Intent Manifest) stored securely in Redis.
+2. **The Interceptor (Decorator/Wrapper)**: Wraps the agent's *tools*. When the agent tries to call a tool, it grabs the active Session, sends the parameters to the Gateway, and blocks execution if it violates the manifest.
+
+> [!IMPORTANT]
+> **Failsafe Design:** If an agent attempts to execute a protected tool *without* an active `argus.Session` context, ARGUS fails closed by throwing an `ArgusException`. This prevents developers from accidentally running dangerous tools unprotected.
+
+---
+
+## Vanilla Python Decorators
+
+For custom tools you write yourself, use the `@argus.protect` decorator. This is completely framework-agnostic and intercepts function execution in plain Python.
+
+```python
+import argus
+from argus import ArgusQuarantineException
+
+@argus.protect(action_type="delete_record", target_arg="record_id", target_type="database")
+def delete_database_record(record_id: str, table: str):
+    # This core code will NOT run unless ARGUS approves it first
+    db.query(f"DELETE FROM {table} WHERE id = {record_id}")
+    return True
+
+# Running the agent safely
+user_prompt = "Delete records associated with user session #12"
+
+with argus.Session(user_prompt=user_prompt):
+    try:
+        # ✅ ALLOWED: record_id aligns with user intent
+        delete_database_record(record_id="12", table="users") 
+        
+        # ❌ BLOCKED: Agent goes rogue and tries to wipe the admin config!
+        # Raises ArgusQuarantineException instantly
+        delete_database_record(record_id="admin_config", table="system_settings")
+        
+    except ArgusQuarantineException as e:
+        print(f"🛑 Security Boundary Violated: {e.explanation}")
+```
+
+---
+
+## Framework Integrations
+
+### LangChain
+LangChain uses structured `BaseTool` objects. Since you import many pre-built tools directly from LangChain's ecosystem, you cannot add decorators directly to their source code. Use our native `wrap_langchain_tool` helper:
+
+```python
+from langchain_community.tools import ShellTool
+from argus.integrations.langchain import wrap_langchain_tool
+import argus
+
+# 1. Instantiate the tool
+raw_shell_tool = ShellTool()
+
+# 2. Wrap it with ARGUS
+protected_shell = wrap_langchain_tool(
+    tool=raw_shell_tool,
+    action_type="execute_code",
+    target_type="shell"
+)
+
+# 3. Use it in LangChain agents normally!
+with argus.Session("List files in the current directory"):
+    # This will succeed
+    protected_shell.run({"commands": ["ls -la"]})
+    
+    # This will raise ArgusQuarantineException and block
+    protected_shell.run({"commands": ["rm -rf /"]})
+```
+
+---
+
+### PydanticAI
+PydanticAI agent tools are standard python functions decorated with `@agent.tool`. Stack the `@argus.protect` decorator underneath the tool registration to secure it:
+
+```python
+from pydantic_ai import Agent
+import argus
+
+agent = Agent('openai:gpt-4o')
+
+@argus.protect(action_type="read_file", target_arg="filepath", target_type="file")
+@agent.tool
+def read_system_file(ctx, filepath: str) -> str:
+    with open(filepath, 'r') as f:
+        return f.read()
+
+# Execute securely
+with argus.Session("Read my diary.txt"):
+    agent.run_sync("Read my diary.txt")  # Succeeds or Fails depending on prompt
+```
+
+---
+
+### CrewAI / AutoGen
+CrewAI agents use class-based tools. We can easily wrap standard CrewAI tools by wrapping their `_run` methods or decorating their initialization:
+
+```python
+from crewai.tools import BaseTool
+import argus
+
+class CustomWriteTool(BaseTool):
+    name: str = "Write File"
+    description: str = "Writes a file to disk."
+    
+    def _run(self, filename: str, content: str) -> str:
+        with open(filename, 'w') as f:
+            f.write(content)
+        return "Success"
+
+# Secure the tool class at runtime
+protected_tool = CustomWriteTool()
+# Dynamically monkeypatch or wrap the execution
+protected_tool._run = argus.protect(action_type="write_file", target_arg="filename")(protected_tool._run)
+```
+
+---
+
+## Security Paradigms
+
+ARGUS utilizes a **Multi-Layer Defense Matrix**:
+
+| Layer | Component | Defense Type | Execution Speed |
+| :--- | :--- | :--- | :--- |
+| **Layer 1** | Intent Extraction | Pre-Action Intent Mapping | Sub-300ms |
+| **Layer 2** | Lobster Trap | Local Semantic Policies | Sub-10ms |
+| **Layer 3** | Explanation Engine | Deep Post-Flag Reasoning | Async Background |
+| **Layer 4** | Human Gate | Manual Action Quarantine | Human Speed |
+
+### The Quarantine Lifecycle
+When an action is flagged by **Layer 2 (Lobster Trap)**:
+1. The tool execution is **immediately blocked** in Python (an exception is raised).
+2. The blocked action payload is saved to the Gateway database as `QUARANTINE`.
+3. The explanation engine runs in the background to provide a detailed, plain-text security report explaining *why* it was blocked.
+4. The action appears in the **ARGUS Dashboard Review Queue**, where security administrators can manually audit the prompt, inspect the parameters, and decide to `APPROVE` or `DENY` future runs.
+
+---
+
+## API Reference
+
+### `argus.Session`
+Context manager for establishing a security boundary.
+```python
+with argus.Session(user_prompt: str, user_id: Optional[str] = None):
+    # Agent operations here
+```
+
+### `@argus.protect`
+Function decorator to intercept execution.
+```python
+@argus.protect(
+    action_type: str, 
+    target_arg: Optional[str] = None, 
+    target_type: str = "api"
+)
+```
+*   `action_type`: The category of action (e.g., `send_email`, `write_file`).
+*   `target_arg`: The name of the function parameter containing the target resource (e.g., `filepath`).
+*   `target_type`: The resource type (e.g., `file`, `email`, `database`).
+
+### `ArgusQuarantineException`
+Exception thrown when an action is blocked.
+*   `explanation`: Plain-text justification of why the action violated user intent.
+*   `raw_response`: Direct JSON response dictionary from the ARGUS Gateway.

argus_shield-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: argus-shield
+Version: 0.1.0
+Summary: ARGUS Python SDK - Framework-agnostic AI agent guardrails and safety tool
+Author-email: Tanish Rajput <tanishrajput9@gmail.com>
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Description-Content-Type: text/markdown
+
+# ARGUS Python SDK
+
+The official Python SDK for [ARGUS](https://github.com/tanishra/argus) — the Agent Runtime Guardrail & Unauthorized-action Stopper.
+
+Securing what AI agents **do** — not just what they hear.
+
+## Installation
+
+You can install the SDK via pip:
+
+```bash
+pip install argus-sdk
+```
+
+Or using `uv`:
+
+```bash
+uv add argus-sdk
+```
+
+## Quick Start
+
+### 1. Set your Environment Variables
+
+```bash
+export ARGUS_API_KEY="your-api-key"
+export ARGUS_BASE_URL="http://localhost:8000"
+```
+
+### 2. Protect Your Tools
+
+Wrap your critical agent tools with the `@argus.protect` decorator.
+
+```python
+import argus
+
+@argus.protect(action_type="send_email", target_type="email")
+def send_email(to_address: str, subject: str, body: str):
+    # This function will ONLY execute if ARGUS approves the action
+    print(f"Sending email to {to_address}...")
+    return True
+```
+
+### 3. Run the Agent within a Session
+
+When a user submits a prompt, wrap the execution in an `argus.Session`. This automatically extracts the user's intent and establishes a temporary authorization boundary.
+
+```python
+import argus
+from argus import ArgusQuarantineException
+
+prompt = "Send the Q3 report to alice@example.com"
+
+# 1. Extract Intent and start session
+with argus.Session(user_prompt=prompt):
+    try:
+        # Agent decides to execute the tool
+        send_email(to_address="alice@example.com", subject="Q3 Report", body="Attached.")
+        print("Success!")
+        
+        # If the agent goes rogue and tries to email someone else:
+        send_email(to_address="eve@example.com", subject="Q3 Report", body="Attached.")
+        
+    except ArgusQuarantineException as e:
+        print(f"Agent was stopped! Reason: {e.explanation}")
+```
+
+## Integrations
+
+### LangChain
+
+ARGUS provides native wrappers for LangChain tools.
+
+```python
+from argus.integrations.langchain import wrap_langchain_tool
+from langchain_core.tools import tool
+
+@tool
+def read_patient_record(patient_id: str) -> str:
+    """Reads a patient record."""
+    return "Patient Data"
+
+# Wrap the tool
+protected_tool = wrap_langchain_tool(
+    tool=read_patient_record,
+    action_type="read_patient_record",
+    target_type="patient_record"
+)
+
+# Use it within an argus.Session normally!
+```

argus_shield-0.1.0/README.md

@@ -0,0 +1,91 @@
+# ARGUS Python SDK
+
+The official Python SDK for [ARGUS](https://github.com/tanishra/argus) — the Agent Runtime Guardrail & Unauthorized-action Stopper.
+
+Securing what AI agents **do** — not just what they hear.
+
+## Installation
+
+You can install the SDK via pip:
+
+```bash
+pip install argus-sdk
+```
+
+Or using `uv`:
+
+```bash
+uv add argus-sdk
+```
+
+## Quick Start
+
+### 1. Set your Environment Variables
+
+```bash
+export ARGUS_API_KEY="your-api-key"
+export ARGUS_BASE_URL="http://localhost:8000"
+```
+
+### 2. Protect Your Tools
+
+Wrap your critical agent tools with the `@argus.protect` decorator.
+
+```python
+import argus
+
+@argus.protect(action_type="send_email", target_type="email")
+def send_email(to_address: str, subject: str, body: str):
+    # This function will ONLY execute if ARGUS approves the action
+    print(f"Sending email to {to_address}...")
+    return True
+```
+
+### 3. Run the Agent within a Session
+
+When a user submits a prompt, wrap the execution in an `argus.Session`. This automatically extracts the user's intent and establishes a temporary authorization boundary.
+
+```python
+import argus
+from argus import ArgusQuarantineException
+
+prompt = "Send the Q3 report to alice@example.com"
+
+# 1. Extract Intent and start session
+with argus.Session(user_prompt=prompt):
+    try:
+        # Agent decides to execute the tool
+        send_email(to_address="alice@example.com", subject="Q3 Report", body="Attached.")
+        print("Success!")
+        
+        # If the agent goes rogue and tries to email someone else:
+        send_email(to_address="eve@example.com", subject="Q3 Report", body="Attached.")
+        
+    except ArgusQuarantineException as e:
+        print(f"Agent was stopped! Reason: {e.explanation}")
+```
+
+## Integrations
+
+### LangChain
+
+ARGUS provides native wrappers for LangChain tools.
+
+```python
+from argus.integrations.langchain import wrap_langchain_tool
+from langchain_core.tools import tool
+
+@tool
+def read_patient_record(patient_id: str) -> str:
+    """Reads a patient record."""
+    return "Patient Data"
+
+# Wrap the tool
+protected_tool = wrap_langchain_tool(
+    tool=read_patient_record,
+    action_type="read_patient_record",
+    target_type="patient_record"
+)
+
+# Use it within an argus.Session normally!
+```

argus_shield-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "argus-shield"
+version = "0.1.0"
+description = "ARGUS Python SDK - Framework-agnostic AI agent guardrails and safety tool"
+readme = "README.md"
+authors = [
+    { name = "Tanish Rajput", email = "tanishrajput9@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+]
+

argus_shield-0.1.0/src/argus/__init__.py

@@ -0,0 +1,21 @@
+"""
+ARGUS Python SDK
+Securing what AI agents do, not just what they hear.
+"""
+
+from .client import ArgusClient, AsyncArgusClient
+from .decorators import protect
+from .exceptions import ArgusException, ArgusQuarantineException, ArgusAPIError
+from .session import Session, AsyncSession, get_current_session
+
+__all__ = [
+    "ArgusClient",
+    "AsyncArgusClient",
+    "protect",
+    "ArgusException",
+    "ArgusQuarantineException",
+    "ArgusAPIError",
+    "Session",
+    "AsyncSession",
+    "get_current_session",
+]