argus-shield 0.1.0__py3-none-any.whl

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",
+]

argus/client.py

@@ -0,0 +1,133 @@
+import os
+from typing import Dict, Any, Optional
+import httpx
+
+from .exceptions import ArgusAPIError
+
+
+class ArgusClient:
+    """
+    Synchronous client for the ARGUS Gateway API.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, api_key: Optional[str] = None):
+        self.base_url = (base_url or os.getenv("ARGUS_BASE_URL", "https://tanishra-argus.hf.space")).rstrip(
+            "/"
+        )
+        self.api_key = api_key or os.getenv("ARGUS_API_KEY", "")
+
+        headers = {}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+
+        self.http = httpx.Client(base_url=self.base_url, headers=headers)
+
+    def extract_intent(self, user_prompt: str, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Sends a user prompt to the ARGUS Gateway to extract an Intent Manifest and start a session.
+        """
+        payload = {"user_prompt": user_prompt}
+        if user_id:
+            payload["user_id"] = user_id
+
+        try:
+            resp = self.http.post("/api/intent/extract", json=payload)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise ArgusAPIError(f"API Error: {e.response.text}", status_code=e.response.status_code)
+        except httpx.RequestError as e:
+            raise ArgusAPIError(f"Network error connecting to ARGUS: {e}")
+
+    def evaluate_action(
+        self,
+        session_id: str,
+        action_type: str,
+        target: str,
+        target_type: str = "api",
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Evaluates a pending agent action against the active session's Intent Manifest.
+        """
+        payload = {
+            "session_id": session_id,
+            "action_type": action_type,
+            "target": target,
+            "target_type": target_type,
+            "parameters": parameters or {},
+        }
+
+        try:
+            resp = self.http.post("/api/evaluate", json=payload)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise ArgusAPIError(f"API Error: {e.response.text}", status_code=e.response.status_code)
+        except httpx.RequestError as e:
+            raise ArgusAPIError(f"Network error connecting to ARGUS: {e}")
+
+    def close(self):
+        self.http.close()
+
+
+class AsyncArgusClient:
+    """
+    Asynchronous client for the ARGUS Gateway API.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, api_key: Optional[str] = None):
+        self.base_url = (base_url or os.getenv("ARGUS_BASE_URL", "https://tanishra-argus.hf.space")).rstrip(
+            "/"
+        )
+        self.api_key = api_key or os.getenv("ARGUS_API_KEY", "")
+
+        headers = {}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+
+        self.http = httpx.AsyncClient(base_url=self.base_url, headers=headers)
+
+    async def extract_intent(
+        self, user_prompt: str, user_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        payload = {"user_prompt": user_prompt}
+        if user_id:
+            payload["user_id"] = user_id
+
+        try:
+            resp = await self.http.post("/api/intent/extract", json=payload)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise ArgusAPIError(f"API Error: {e.response.text}", status_code=e.response.status_code)
+        except httpx.RequestError as e:
+            raise ArgusAPIError(f"Network error connecting to ARGUS: {e}")
+
+    async def evaluate_action(
+        self,
+        session_id: str,
+        action_type: str,
+        target: str,
+        target_type: str = "api",
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        payload = {
+            "session_id": session_id,
+            "action_type": action_type,
+            "target": target,
+            "target_type": target_type,
+            "parameters": parameters or {},
+        }
+
+        try:
+            resp = await self.http.post("/api/evaluate", json=payload)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            raise ArgusAPIError(f"API Error: {e.response.text}", status_code=e.response.status_code)
+        except httpx.RequestError as e:
+            raise ArgusAPIError(f"Network error connecting to ARGUS: {e}")
+
+    async def close(self):
+        await self.http.aclose()

argus/decorators.py

@@ -0,0 +1,110 @@
+import functools
+import inspect
+from typing import Any, Callable, Dict, Optional, TypeVar, cast
+
+from .exceptions import ArgusException, ArgusQuarantineException
+from .session import get_current_session
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def protect(
+    action_type: str, target_arg: Optional[str] = None, target_type: str = "api"
+) -> Callable[[F], F]:
+    """
+    Decorator that protects a function/tool by evaluating its parameters against the active ARGUS session.
+
+    :param action_type: The generic type of action (e.g., 'send_email', 'write_file', 'query_db').
+    :param target_arg: The name of the function argument that represents the target (e.g., 'to_address').
+                       If None, the first argument or a generic 'system' target is used.
+    :param target_type: The type of target (e.g., 'email', 'file', 'api', 'database').
+    """
+
+    def decorator(func: F) -> F:
+        sig = inspect.signature(func)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            session = get_current_session()
+            if not session:
+                # If there's no active session, we run unprotected, or we could fail closed.
+                # For safety, failing closed is better for a security product, but for beta,
+                # we'll raise an explicit exception requiring a session.
+                raise ArgusException(
+                    "No active ARGUS session. Use `with argus.Session(prompt):` before calling protected tools."
+                )
+
+            # Bind arguments
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            params = dict(bound_args.arguments)
+
+            # Determine target
+            target_val = "unknown"
+            if target_arg and target_arg in params:
+                target_val = str(params[target_arg])
+            elif params:
+                # Fallback to first parameter
+                target_val = str(next(iter(params.values())))
+
+            # Evaluate against ARGUS
+            eval_resp = session.client.evaluate_action(
+                session_id=session.session_id,
+                action_type=action_type,
+                target=target_val,
+                target_type=target_type,
+                parameters=params,
+            )
+
+            decision = eval_resp.get("decision", "QUARANTINE")
+            if decision in ["QUARANTINE", "DENY"]:
+                raise ArgusQuarantineException(
+                    message=f"Action '{action_type}' was blocked by ARGUS.",
+                    explanation=eval_resp.get("reason", "No reason provided."),
+                    raw_response=eval_resp,
+                )
+
+            # Execution allowed
+            return func(*args, **kwargs)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            session = get_current_session()
+            if not session:
+                raise ArgusException(
+                    "No active ARGUS session. Use `async with argus.AsyncSession(prompt):` before calling protected tools."
+                )
+
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+            params = dict(bound_args.arguments)
+
+            target_val = "unknown"
+            if target_arg and target_arg in params:
+                target_val = str(params[target_arg])
+            elif params:
+                target_val = str(next(iter(params.values())))
+
+            eval_resp = await session.client.evaluate_action(
+                session_id=session.session_id,
+                action_type=action_type,
+                target=target_val,
+                target_type=target_type,
+                parameters=params,
+            )
+
+            decision = eval_resp.get("decision", "QUARANTINE")
+            if decision in ["QUARANTINE", "DENY"]:
+                raise ArgusQuarantineException(
+                    message=f"Action '{action_type}' was blocked by ARGUS.",
+                    explanation=eval_resp.get("reason", "No reason provided."),
+                    raw_response=eval_resp,
+                )
+
+            return await func(*args, **kwargs)
+
+        if inspect.iscoroutinefunction(func):
+            return cast(F, async_wrapper)
+        return cast(F, sync_wrapper)
+
+    return decorator

argus/exceptions.py

@@ -0,0 +1,28 @@
+"""
+Exceptions for the ARGUS SDK.
+"""
+
+
+class ArgusException(Exception):
+    """Base exception for all ARGUS SDK errors."""
+
+    pass
+
+
+class ArgusQuarantineException(ArgusException):
+    """
+    Raised when ARGUS intercepts and blocks/quarantines an action.
+    """
+
+    def __init__(self, message: str, explanation: str = "", raw_response: dict | None = None):
+        super().__init__(message)
+        self.explanation = explanation
+        self.raw_response = raw_response or {}
+
+
+class ArgusAPIError(ArgusException):
+    """Raised when the ARGUS API returns an error or is unreachable."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code

argus/integrations/autogen.py

@@ -0,0 +1,16 @@
+from typing import Callable, Any
+from ..decorators import protect
+
+
+def wrap_autogen_tool(
+    func: Callable[..., Any], action_type: str, target_type: str = "api"
+) -> Callable[..., Any]:
+    """
+    Wraps an AutoGen function-based tool with ARGUS pre-action authorization.
+    Since AutoGen registers standard Python functions, this maps directly to the protect decorator.
+
+    :param func: The standard python function representing the tool.
+    :param action_type: The generic action type (e.g. 'read_file').
+    :param target_type: The target type (e.g. 'file', 'email').
+    """
+    return protect(action_type=action_type, target_type=target_type)(func)

argus/integrations/crewai.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+try:
+    from crewai.tools import BaseTool
+except ImportError:
+    BaseTool = None
+
+from ..exceptions import ArgusException, ArgusQuarantineException
+from ..session import get_current_session
+
+
+def wrap_crewai_tool(tool: Any, action_type: str, target_type: str = "api") -> Any:
+    """
+    Wraps a CrewAI BaseTool with ARGUS pre-action authorization.
+
+    :param tool: A CrewAI BaseTool instance.
+    :param action_type: The generic action type (e.g. 'read_file').
+    :param target_type: The target type (e.g. 'file', 'email').
+    """
+    if BaseTool is None or not isinstance(tool, BaseTool):
+        raise ArgusException(
+            "CrewAI is not installed or the provided object is not a CrewAI BaseTool. "
+            "Please install crewai."
+        )
+
+    original_run = tool._run
+
+    def argus_run(*args, **kwargs):
+        session = get_current_session()
+        if not session:
+            raise ArgusException(
+                "No active ARGUS session. Use `with argus.Session(prompt):` before running the agent."
+            )
+
+        params = kwargs.copy()
+        if args:
+            params["_positional_args"] = args
+
+        target_val = "unknown"
+        if params:
+            target_val = str(next(iter(params.values())))
+
+        eval_resp = session.client.evaluate_action(
+            session_id=session.session_id,
+            action_type=action_type,
+            target=target_val,
+            target_type=target_type,
+            parameters=params,
+        )
+
+        decision = eval_resp.get("decision", "QUARANTINE")
+        if decision in ["QUARANTINE", "DENY"]:
+            raise ArgusQuarantineException(
+                message=f"Action '{action_type}' was blocked by ARGUS.",
+                explanation=eval_resp.get("reason", "No reason provided."),
+                raw_response=eval_resp,
+            )
+
+        return original_run(*args, **kwargs)
+
+    tool._run = argus_run
+    return tool

argus/integrations/langchain.py

@@ -0,0 +1,101 @@
+from typing import Any, Callable
+
+try:
+    from langchain_core.tools import BaseTool
+except ImportError:
+    BaseTool = None
+
+from ..exceptions import ArgusException, ArgusQuarantineException
+from ..session import get_current_session
+
+
+def wrap_langchain_tool(tool: Any, action_type: str, target_type: str = "api") -> Any:
+    """
+    Wraps a LangChain tool with ARGUS pre-action authorization.
+
+    :param tool: A LangChain BaseTool instance.
+    :param action_type: The generic action type this tool performs (e.g. 'read_file').
+    :param target_type: The target type (e.g. 'file', 'email', 'api').
+    """
+    if BaseTool is None or not isinstance(tool, BaseTool):
+        raise ArgusException(
+            "LangChain is not installed or the provided object is not a BaseTool. Please install langchain-core."
+        )
+
+    original_run = tool._run
+    original_arun = tool._arun
+
+    def argus_run(*args, **kwargs):
+        session = get_current_session()
+        if not session:
+            raise ArgusException(
+                "No active ARGUS session. Use `with argus.Session(prompt):` before running the agent."
+            )
+
+        # Combine args and kwargs into parameters
+        params = kwargs.copy()
+        if args:
+            params["_positional_args"] = args
+
+        target_val = "unknown"
+        if params:
+            # simple heuristic: use the first kwarg as the target
+            target_val = str(next(iter(params.values())))
+
+        eval_resp = session.client.evaluate_action(
+            session_id=session.session_id,
+            action_type=action_type,
+            target=target_val,
+            target_type=target_type,
+            parameters=params,
+        )
+
+        decision = eval_resp.get("decision", "QUARANTINE")
+        if decision in ["QUARANTINE", "DENY"]:
+            raise ArgusQuarantineException(
+                message=f"Action '{action_type}' was blocked by ARGUS.",
+                explanation=eval_resp.get("reason", "No reason provided."),
+                raw_response=eval_resp,
+            )
+
+        return original_run(*args, **kwargs)
+
+    async def argus_arun(*args, **kwargs):
+        session = get_current_session()
+        if not session:
+            raise ArgusException(
+                "No active ARGUS session. Use `async with argus.AsyncSession(prompt):` before running the agent."
+            )
+
+        params = kwargs.copy()
+        if args:
+            params["_positional_args"] = args
+
+        target_val = "unknown"
+        if params:
+            target_val = str(next(iter(params.values())))
+
+        eval_resp = await session.client.evaluate_action(
+            session_id=session.session_id,
+            action_type=action_type,
+            target=target_val,
+            target_type=target_type,
+            parameters=params,
+        )
+
+        decision = eval_resp.get("decision", "QUARANTINE")
+        if decision in ["QUARANTINE", "DENY"]:
+            raise ArgusQuarantineException(
+                message=f"Action '{action_type}' was blocked by ARGUS.",
+                explanation=eval_resp.get("reason", "No reason provided."),
+                raw_response=eval_resp,
+            )
+
+        return await original_arun(*args, **kwargs)
+
+    # Override the methods
+    tool._run = argus_run
+    if hasattr(tool, "_arun"):
+        tool._arun = argus_arun
+
+    return tool

argus/integrations/pydantic_ai.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+try:
+    from pydantic_ai.tools import Tool
+except ImportError:
+    Tool = None
+
+from ..decorators import protect
+from ..exceptions import ArgusException
+
+
+def wrap_pydantic_ai_tool(tool: Any, action_type: str, target_type: str = "api") -> Any:
+    """
+    Wraps PydanticAI tools with ARGUS protection. Can wrap either raw function tools or
+    explicit Tool model classes.
+
+    :param tool: A callable function or a PydanticAI Tool instance.
+    :param action_type: The generic action type (e.g. 'read_file').
+    :param target_type: The target type (e.g. 'file', 'email').
+    """
+    if Tool is not None and isinstance(tool, Tool):
+        # Wrap the tool function inside PydanticAI's Tool wrapper
+        original_function = tool.function
+        tool.function = protect(action_type=action_type, target_type=target_type)(original_function)
+        return tool
+
+    if callable(tool):
+        # If it's a raw function, wrap it directly with the protect decorator
+        return protect(action_type=action_type, target_type=target_type)(tool)
+
+    raise ArgusException(
+        "Provided tool is neither a raw callable nor a valid PydanticAI Tool class instance."
+    )

argus/local_engine.py

@@ -0,0 +1,251 @@
+import os
+import uuid
+import json
+import re
+from typing import Dict, Any, Optional, List
+import httpx
+
+from .exceptions import ArgusException
+
+
+class LocalEvaluationEngine:
+    """
+    Fully offline/embedded evaluation engine for ARGUS.
+    Uses developer's local API keys (Gemini or OpenAI) if available for deep semantic check,
+    or falls back to a high-fidelity heuristic rule engine.
+    """
+
+    def __init__(self):
+        self.gemini_key = os.getenv("GEMINI_API_KEY", "")
+        self.openai_key = os.getenv("OPENAI_API_KEY", "")
+
+    def extract_intent(self, user_prompt: str) -> Dict[str, Any]:
+        session_id = f"sess-local-{uuid.uuid4()}"
+
+        # 1. Try semantic extraction with LLM if key is present
+        if self.gemini_key:
+            try:
+                return {
+                    "session_id": session_id,
+                    "manifest": self._extract_with_gemini(user_prompt)
+                }
+            except Exception:
+                # Fallback to heuristic if API call fails
+                pass
+
+        if self.openai_key:
+            try:
+                return {
+                    "session_id": session_id,
+                    "manifest": self._extract_with_openai(user_prompt)
+                }
+            except Exception:
+                # Fallback to heuristic
+                pass
+
+        # 2. Heuristic rule extraction (fully offline, zero cost)
+        return {
+            "session_id": session_id,
+            "manifest": self._extract_heuristics(user_prompt)
+        }
+
+    def evaluate_action(
+        self,
+        manifest: Dict[str, Any],
+        action_type: str,
+        target: str,
+        target_type: str,
+        parameters: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Evaluates action locally using manifest boundaries.
+        """
+        allowed_actions = manifest.get("allowed_actions", [])
+        restricted_targets = manifest.get("restricted_targets", [])
+
+        # Standard check: is the action type allowed?
+        if action_type not in allowed_actions:
+            return {
+                "decision": "QUARANTINE",
+                "reason": f"Action '{action_type}' is not authorized by the user prompt intent."
+            }
+
+        # Target-specific checks
+        if restricted_targets:
+            # Check if any restricted targets are in the current action target
+            matched = False
+            for t in restricted_targets:
+                if t.lower() in target.lower() or target.lower() in t.lower():
+                    matched = True
+                    break
+            
+            # For actions like read_file or fetch_url, if targets were specified, limit to those targets
+            if action_type in ["read_file", "write_file", "send_email", "fetch_url"] and not matched:
+                # If target is generic, let's allow it, but if it contradicts the prompt targets, deny
+                pass
+
+        # If LLM keys are available, run a semantic audit check for critical/sensitive actions
+        if action_type in ["run_command", "send_email"] and (self.gemini_key or self.openai_key):
+            try:
+                return self._evaluate_with_llm(manifest.get("user_prompt", ""), action_type, target, parameters)
+            except Exception:
+                pass
+
+        return {
+            "decision": "ALLOW",
+            "reason": f"Action '{action_type}' with target '{target}' matches intent manifest."
+        }
+
+    def _extract_heuristics(self, prompt: str) -> Dict[str, Any]:
+        prompt_lower = prompt.lower()
+        allowed = []
+        targets = []
+
+        # Heuristic actions detection
+        if any(w in prompt_lower for w in ["read", "view", "open", "cat", "print", "file", "text"]):
+            allowed.append("read_file")
+        if any(w in prompt_lower for w in ["write", "create", "save", "make", "output", "update"]):
+            allowed.append("write_file")
+        if any(w in prompt_lower for w in ["email", "mail", "send", "notify"]):
+            allowed.append("send_email")
+        if any(w in prompt_lower for w in ["http", "url", "web", "fetch", "get", "download", "scrape"]):
+            allowed.append("fetch_url")
+        if any(w in prompt_lower for w in ["run", "execute", "bash", "shell", "command", "terminal"]):
+            allowed.append("run_command")
+        
+        # Heuristically add custom action
+        allowed.append("custom_action")
+
+        # Basic target extraction (looks for filename patterns or domain names)
+        file_matches = re.findall(r'[\w\-]+\.[a-zA-Z0-9]+', prompt)
+        if file_matches:
+            targets.extend(file_matches)
+
+        email_matches = re.findall(r'[\w\.-]+@[\w\.-]+', prompt)
+        if email_matches:
+            targets.extend(email_matches)
+
+        return {
+            "user_prompt": prompt,
+            "allowed_actions": list(set(allowed)),
+            "restricted_targets": list(set(targets))
+        }
+
+    def _extract_with_gemini(self, prompt: str) -> Dict[str, Any]:
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key={self.gemini_key}"
+        
+        system_instruction = (
+            "You are the ARGUS security intent extractor. Analyze the user prompt and identify "
+            "what general action categories and targets are authorized by the user.\n"
+            "Action categories MUST be selected from: ['read_file', 'write_file', 'send_email', 'fetch_url', 'run_command', 'custom_action']."
+        )
+
+        payload = {
+            "contents": [{
+                "parts": [{"text": f"{system_instruction}\n\nUser Prompt: {prompt}\n\nExtract authorized actions and targets."}]
+            }],
+            "generationConfig": {
+                "responseMimeType": "application/json",
+                "responseSchema": {
+                    "type": "OBJECT",
+                    "properties": {
+                        "allowed_actions": {
+                            "type": "ARRAY",
+                            "items": {"type": "STRING"}
+                        },
+                        "restricted_targets": {
+                            "type": "ARRAY",
+                            "items": {"type": "STRING"}
+                        }
+                    },
+                    "required": ["allowed_actions", "restricted_targets"]
+                }
+            }
+        }
+
+        resp = httpx.post(url, json=payload, timeout=10.0)
+        resp.raise_for_status()
+        data = resp.json()
+        
+        text = data["candidates"][0]["content"]["parts"][0]["text"]
+        result = json.loads(text)
+        result["user_prompt"] = prompt
+        return result
+
+    def _extract_with_openai(self, prompt: str) -> Dict[str, Any]:
+        url = "https://api.openai.com/v1/chat/completions"
+        headers = {"Authorization": f"Bearer {self.openai_key}"}
+        
+        system_instruction = (
+            "You are the ARGUS security intent extractor. Analyze the user prompt and identify "
+            "what general action categories and targets are authorized by the user.\n"
+            "Action categories MUST be selected from: ['read_file', 'write_file', 'send_email', 'fetch_url', 'run_command', 'custom_action'].\n"
+            "Respond ONLY as a JSON object with keys 'allowed_actions' (list of strings) and 'restricted_targets' (list of strings)."
+        )
+
+        payload = {
+            "model": "gpt-4o-mini",
+            "response_format": {"type": "json_object"},
+            "messages": [
+                {"role": "system", "content": system_instruction},
+                {"role": "user", "content": prompt}
+            ]
+        }
+
+        resp = httpx.post(url, json=payload, headers=headers, timeout=10.0)
+        resp.raise_for_status()
+        data = resp.json()
+        
+        result = json.loads(data["choices"][0]["message"]["content"])
+        result["user_prompt"] = prompt
+        return result
+
+    def _evaluate_with_llm(self, prompt: str, action_type: str, target: str, parameters: Dict[str, Any]) -> Dict[str, Any]:
+        system_instruction = (
+            "You are the ARGUS actions guardrail. Determine if the pending tool execution is safe "
+            "and explicitly authorized by the user's initial prompt.\n"
+            "User Prompt: {prompt}\n"
+            "Pending Action: {action_type}\n"
+            "Target: {target}\n"
+            "Parameters: {params}\n\n"
+            "Respond ONLY with a JSON object in this format:\n"
+            "{{\n"
+            "  \"decision\": \"ALLOW\" or \"QUARANTINE\",\n"
+            "  \"reason\": \"A concise explanation of the decision\"\n"
+            "}}"
+        ).format(prompt=prompt, action_type=action_type, target=target, params=json.dumps(parameters))
+
+        if self.gemini_key:
+            url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key={self.gemini_key}"
+            payload = {
+                "contents": [{"parts": [{"text": system_instruction}]}],
+                "generationConfig": {
+                    "responseMimeType": "application/json",
+                    "responseSchema": {
+                        "type": "OBJECT",
+                        "properties": {
+                            "decision": {"type": "STRING", "enum": ["ALLOW", "QUARANTINE"]},
+                            "reason": {"type": "STRING"}
+                        },
+                        "required": ["decision", "reason"]
+                    }
+                }
+            }
+            resp = httpx.post(url, json=payload, timeout=5.0)
+            resp.raise_for_status()
+            text = resp.json()["candidates"][0]["content"]["parts"][0]["text"]
+            return json.loads(text)
+
+        elif self.openai_key:
+            url = "https://api.openai.com/v1/chat/completions"
+            headers = {"Authorization": f"Bearer {self.openai_key}"}
+            payload = {
+                "model": "gpt-4o-mini",
+                "response_format": {"type": "json_object"},
+                "messages": [{"role": "user", "content": system_instruction}]
+            }
+            resp = httpx.post(url, json=payload, headers=headers, timeout=5.0)
+            resp.raise_for_status()
+            return json.loads(resp.json()["choices"][0]["message"]["content"])
+
+        raise ArgusException("No local LLM keys configured for semantic evaluation.")

argus/session.py

@@ -0,0 +1,150 @@
+import os
+import contextvars
+from typing import Optional, Dict, Any
+from .client import ArgusClient, AsyncArgusClient
+
+_current_session = contextvars.ContextVar("argus_session", default=None)
+
+
+class LocalClientWrapper:
+    def __init__(self, engine, manifest_holder):
+        self.engine = engine
+        self.manifest_holder = manifest_holder
+
+    def extract_intent(self, user_prompt: str, user_id: Optional[str] = None) -> Dict[str, Any]:
+        res = self.engine.extract_intent(user_prompt)
+        self.manifest_holder.manifest = res.get("manifest")
+        self.manifest_holder.session_id = res.get("session_id")
+        return res
+
+    def evaluate_action(
+        self,
+        session_id: str,
+        action_type: str,
+        target: str,
+        target_type: str = "api",
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self.engine.evaluate_action(
+            self.manifest_holder.manifest or {},
+            action_type,
+            target,
+            target_type,
+            parameters or {},
+        )
+
+    def close(self):
+        pass
+
+
+class AsyncLocalClientWrapper:
+    def __init__(self, engine, manifest_holder):
+        self.engine = engine
+        self.manifest_holder = manifest_holder
+
+    async def extract_intent(self, user_prompt: str, user_id: Optional[str] = None) -> Dict[str, Any]:
+        res = self.engine.extract_intent(user_prompt)
+        self.manifest_holder.manifest = res.get("manifest")
+        self.manifest_holder.session_id = res.get("session_id")
+        return res
+
+    async def evaluate_action(
+        self,
+        session_id: str,
+        action_type: str,
+        target: str,
+        target_type: str = "api",
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        return self.engine.evaluate_action(
+            self.manifest_holder.manifest or {},
+            action_type,
+            target,
+            target_type,
+            parameters or {},
+        )
+
+    async def close(self):
+        pass
+
+
+class Session:
+    def __init__(
+        self,
+        user_prompt: str,
+        user_id: Optional[str] = None,
+        client: Optional[ArgusClient] = None,
+        local_mode: Optional[bool] = None,
+    ):
+        self.user_prompt = user_prompt
+        self.user_id = user_id
+        self.session_id: Optional[str] = None
+        self.manifest: Optional[Dict[str, Any]] = None
+        self._token = None
+
+        # Check local mode: explicit parameter or ARGUS_LOCAL_MODE env var
+        self.local_mode = local_mode if local_mode is not None else (
+            os.getenv("ARGUS_LOCAL_MODE", "").lower() == "true"
+        )
+
+        if self.local_mode:
+            from .local_engine import LocalEvaluationEngine
+            self.local_engine = LocalEvaluationEngine()
+            self.client = LocalClientWrapper(self.local_engine, self)
+        else:
+            self.client = client or ArgusClient()
+
+    def __enter__(self):
+        response = self.client.extract_intent(self.user_prompt, self.user_id)
+        self.session_id = response.get("session_id")
+        self.manifest = response.get("manifest")
+        self._token = _current_session.set(self)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._token:
+            _current_session.reset(self._token)
+        self.client.close()
+
+
+class AsyncSession:
+    def __init__(
+        self,
+        user_prompt: str,
+        user_id: Optional[str] = None,
+        client: Optional[AsyncArgusClient] = None,
+        local_mode: Optional[bool] = None,
+    ):
+        self.user_prompt = user_prompt
+        self.user_id = user_id
+        self.session_id: Optional[str] = None
+        self.manifest: Optional[Dict[str, Any]] = None
+        self._token = None
+
+        # Check local mode: explicit parameter or ARGUS_LOCAL_MODE env var
+        self.local_mode = local_mode if local_mode is not None else (
+            os.getenv("ARGUS_LOCAL_MODE", "").lower() == "true"
+        )
+
+        if self.local_mode:
+            from .local_engine import LocalEvaluationEngine
+            self.local_engine = LocalEvaluationEngine()
+            self.client = AsyncLocalClientWrapper(self.local_engine, self)
+        else:
+            self.client = client or AsyncArgusClient()
+
+    async def __aenter__(self):
+        response = await self.client.extract_intent(self.user_prompt, self.user_id)
+        self.session_id = response.get("session_id")
+        self.manifest = response.get("manifest")
+        self._token = _current_session.set(self)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._token:
+            _current_session.reset(self._token)
+        await self.client.close()
+
+
+def get_current_session() -> Optional[Session | AsyncSession]:
+    return _current_session.get()

argus_shield-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+argus/__init__.py,sha256=z6KZZ0NlkAQ79cPHaEEAhght_9QxholxlEVf9bDxzb4,515
+argus/client.py,sha256=eb-9_aAU807BVJwMvGzmRc3yByOEo7XY0nagqxkONjE,4520
+argus/decorators.py,sha256=bax_2Al16_AsX74gIgaPcHKtYuallO2lhB2KzDozTjQ,4311
+argus/exceptions.py,sha256=pnO_s-fCyhPybdCgDc2d9377icsml3xMi7xm7fh1NdE,738
+argus/local_engine.py,sha256=9r4Xvv91uCPp6_wbUa0ardRgnLuwDPkRkxOaNNdOnJM,10406
+argus/session.py,sha256=frJn03SlvusVXyxHIL8jjSe8eKNJGrHmk0dh5YIe7ZQ,4848
+argus/integrations/autogen.py,sha256=Btada3H_52pp39wYuyaHWUqQ7v7urKmmqYKCfqdnEXM,660
+argus/integrations/crewai.py,sha256=dTVYXUZ4V01ZE5r-d0cAK5D2UOm0Lz2PQGaSXBPSWXI,1956
+argus/integrations/langchain.py,sha256=ov0zz-Vdibk7Jrsi2epsMTLW9z_cSIeWoC5Rtl4KAcM,3361
+argus/integrations/pydantic_ai.py,sha256=-EBhHtRKoBSt3ZRIuN7FmwC036s_TAYUIVvnc7EmWHU,1196
+argus_shield-0.1.0.dist-info/METADATA,sha256=GpCEwAy3Q7rMBs6un3SJ_GOcyZj66od87oGdLoSTl5s,2566
+argus_shield-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+argus_shield-0.1.0.dist-info/RECORD,,

argus_shield-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any