xshieldai-langchain 1.0.0__tar.gz

xshieldai_langchain-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: xshieldai-langchain
+Version: 1.0.0
+Summary: xShieldAI / AEGIS DAN gate callback for LangChain agents — pre-execution governance via @xshieldai/aegis
+Author-email: "Capt. Anil Sharma" <capt.anil.sharma@powerpbox.org>
+License: AGPL-3.0
+Project-URL: Homepage, https://xshieldai.com
+Project-URL: Repository, https://github.com/rocketlang/aegis/tree/main/packages/xshieldai-langchain
+Project-URL: Documentation, https://xshieldai.com/docs/langchain
+Keywords: langchain,xshieldai,aegis,ai-governance,agent-safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: langchain-core>=0.1.0; extra == "dev"
+
+# xshieldai-langchain
+
+KavachOS DAN gate callback for LangChain agents.
+
+Intercepts every tool call through the AEGIS KAVACH gate before execution.
+Zero agent code changes — add the callback and every tool invocation is governed.
+
+## Install
+
+```bash
+pip install xshieldai-langchain
+```
+
+## Quick start
+
+```python
+from xshieldai_langchain import KavachGateCallback
+
+callback = KavachGateCallback(
+    base_url="http://localhost:4850",   # AEGIS server
+    on_block="raise",                   # raise KavachGateError on DAN-3/4
+    dry_run=False,
+)
+
+# LangChain agent — pass callback in config
+result = agent.invoke(
+    {"input": "summarise the quarterly report"},
+    config={"callbacks": [callback]},
+)
+
+# Or attach to a single tool:
+result = my_tool.invoke("drop table users", config={"callbacks": [callback]})
+```
+
+## KavachGateCallback parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | `http://localhost:4850` | AEGIS server URL |
+| `token` | `$AEGIS_TOKEN` | Bearer auth token |
+| `on_block` | `"raise"` | `"raise"` → KavachGateError · `"warn"` → print + continue |
+| `dry_run` | `False` | Classify only — no notification, no human-in-loop polling |
+| `tool_name` | `"langchain"` | Label appearing in audit records |
+| `session_id` | auto-generated | Audit grouping key (one per agent session) |
+
+## Direct client
+
+```python
+from xshieldai_langchain import AegisClient
+
+client = AegisClient(base_url="http://localhost:4850")
+
+# Pre-flight budget check
+state = client.state()
+if state["budget"]["breached"]:
+    raise RuntimeError("Daily budget breached — halt")
+
+# Manual gate call
+result = client.gate(command="rm -rf /var/postgres", tool_name="my-agent")
+print(result)  # {"allow": false, "level": 4, "reason": "DAN-4 catastrophic..."}
+
+# Audit query
+records = client.audit(session_id="lc-abc123", status="stop", limit=20)
+```
+
+## How it works
+
+`KavachGateCallback.on_tool_start()` fires before any tool execution.
+It POSTs to `POST /api/v1/kavach/gate` on the AEGIS server.
+
+- **DAN-1/2**: allowed immediately, logged.
+- **DAN-3**: notify approver via Telegram/WhatsApp, wait for ALLOW/STOP.
+- **DAN-4**: blocked immediately, `KavachGateError` raised.
+
+All policy is in AEGIS — the callback is a thin HTTP relay.
+
+## AEGIS server
+
+Run with: `bun /root/aegis/src/dashboard/server.ts`  
+Default port: `4850`  
+Gate endpoint: `POST /api/v1/kavach/gate`
+
+## License
+
+AGPL-3.0 — see [LICENSE](../../LICENSE).

xshieldai_langchain-1.0.0/README.md

@@ -0,0 +1,85 @@
+# xshieldai-langchain
+
+KavachOS DAN gate callback for LangChain agents.
+
+Intercepts every tool call through the AEGIS KAVACH gate before execution.
+Zero agent code changes — add the callback and every tool invocation is governed.
+
+## Install
+
+```bash
+pip install xshieldai-langchain
+```
+
+## Quick start
+
+```python
+from xshieldai_langchain import KavachGateCallback
+
+callback = KavachGateCallback(
+    base_url="http://localhost:4850",   # AEGIS server
+    on_block="raise",                   # raise KavachGateError on DAN-3/4
+    dry_run=False,
+)
+
+# LangChain agent — pass callback in config
+result = agent.invoke(
+    {"input": "summarise the quarterly report"},
+    config={"callbacks": [callback]},
+)
+
+# Or attach to a single tool:
+result = my_tool.invoke("drop table users", config={"callbacks": [callback]})
+```
+
+## KavachGateCallback parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | `http://localhost:4850` | AEGIS server URL |
+| `token` | `$AEGIS_TOKEN` | Bearer auth token |
+| `on_block` | `"raise"` | `"raise"` → KavachGateError · `"warn"` → print + continue |
+| `dry_run` | `False` | Classify only — no notification, no human-in-loop polling |
+| `tool_name` | `"langchain"` | Label appearing in audit records |
+| `session_id` | auto-generated | Audit grouping key (one per agent session) |
+
+## Direct client
+
+```python
+from xshieldai_langchain import AegisClient
+
+client = AegisClient(base_url="http://localhost:4850")
+
+# Pre-flight budget check
+state = client.state()
+if state["budget"]["breached"]:
+    raise RuntimeError("Daily budget breached — halt")
+
+# Manual gate call
+result = client.gate(command="rm -rf /var/postgres", tool_name="my-agent")
+print(result)  # {"allow": false, "level": 4, "reason": "DAN-4 catastrophic..."}
+
+# Audit query
+records = client.audit(session_id="lc-abc123", status="stop", limit=20)
+```
+
+## How it works
+
+`KavachGateCallback.on_tool_start()` fires before any tool execution.
+It POSTs to `POST /api/v1/kavach/gate` on the AEGIS server.
+
+- **DAN-1/2**: allowed immediately, logged.
+- **DAN-3**: notify approver via Telegram/WhatsApp, wait for ALLOW/STOP.
+- **DAN-4**: blocked immediately, `KavachGateError` raised.
+
+All policy is in AEGIS — the callback is a thin HTTP relay.
+
+## AEGIS server
+
+Run with: `bun /root/aegis/src/dashboard/server.ts`  
+Default port: `4850`  
+Gate endpoint: `POST /api/v1/kavach/gate`
+
+## License
+
+AGPL-3.0 — see [LICENSE](../../LICENSE).

xshieldai_langchain-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xshieldai-langchain"
+version = "1.0.0"
+description = "xShieldAI / AEGIS DAN gate callback for LangChain agents — pre-execution governance via @xshieldai/aegis"
+readme = "README.md"
+license = { text = "AGPL-3.0" }
+authors = [{ name = "Capt. Anil Sharma", email = "capt.anil.sharma@powerpbox.org" }]
+keywords = ["langchain", "xshieldai", "aegis", "ai-governance", "agent-safety"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU Affero General Public License v3",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Security",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+dev = ["pytest>=7", "langchain-core>=0.1.0"]
+
+[project.urls]
+Homepage = "https://xshieldai.com"
+Repository = "https://github.com/rocketlang/aegis/tree/main/packages/xshieldai-langchain"
+Documentation = "https://xshieldai.com/docs/langchain"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xshieldai_langchain*"]

xshieldai_langchain-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xshieldai_langchain-1.0.0/xshieldai_langchain/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# xshieldai-langchain — KavachOS governance callbacks for LangChain agents
+# @rule:AEG-012 framework-agnostic: thin HTTP client, all policy in aegis
+# @rule:KAV-001 every dangerous action intercepted before execution
+# @rule:INF-KAV-025 LangChain callback intercepts tool calls at on_tool_start
+
+from .gate import KavachGateCallback, KavachGateError, AegisClient
+
+__all__ = ["KavachGateCallback", "KavachGateError", "AegisClient"]
+__version__ = "1.0.0"

xshieldai_langchain-1.0.0/xshieldai_langchain/gate.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# @rule:KAV-001 every dangerous action intercepted before execution
+# @rule:AEG-011 framework-agnostic: thin HTTP client, all policy in aegis
+# @rule:AEG-012 LangChain adapter is the deployment surface for aegis governance
+# @rule:INF-KAV-025 on_tool_start fires before any tool execution — correct interception point
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from typing import Any, Dict, Optional, Union
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+
+class KavachGateError(Exception):
+    """Raised when the KAVACH gate blocks an action."""
+
+    def __init__(self, command: str, level: int, reason: str, approval_id: Optional[str] = None):
+        self.command = command
+        self.level = level
+        self.reason = reason
+        self.approval_id = approval_id
+        super().__init__(
+            f"KAVACH blocked (DAN-{level}): {reason}"
+            + (f" [approval_id={approval_id}]" if approval_id else "")
+        )
+
+
+class AegisClient:
+    """Thin HTTP client for the AEGIS KAVACH gate API.
+
+    All policy is enforced in the AEGIS server — this client just relays calls.
+    stdlib only: no httpx/requests dependency.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:4850",
+        token: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token or os.environ.get("AEGIS_TOKEN")
+        self.timeout = timeout
+
+    def _headers(self) -> Dict[str, str]:
+        h = {"Content-Type": "application/json"}
+        if self.token:
+            h["Authorization"] = f"Bearer {self.token}"
+        return h
+
+    def _post(self, path: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        data = json.dumps(payload).encode()
+        req = Request(url, data=data, headers=self._headers(), method="POST")
+        try:
+            with urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read())
+        except HTTPError as e:
+            body = e.read().decode(errors="replace")
+            raise RuntimeError(f"Aegis HTTP {e.code} at {url}: {body}") from e
+        except URLError as e:
+            raise RuntimeError(f"Cannot reach Aegis at {url}: {e.reason}") from e
+
+    def _get(self, path: str, params: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+        qs = ""
+        if params:
+            from urllib.parse import urlencode
+            qs = "?" + urlencode({k: v for k, v in params.items() if v is not None})
+        url = f"{self.base_url}{path}{qs}"
+        req = Request(url, headers={k: v for k, v in self._headers().items() if k != "Content-Type"})
+        try:
+            with urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read())
+        except HTTPError as e:
+            body = e.read().decode(errors="replace")
+            raise RuntimeError(f"Aegis HTTP {e.code} at {url}: {body}") from e
+        except URLError as e:
+            raise RuntimeError(f"Cannot reach Aegis at {url}: {e.reason}") from e
+
+    def gate(
+        self,
+        command: str,
+        tool_name: str = "langchain",
+        session_id: Optional[str] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        """POST /api/v1/kavach/gate — returns gate result dict."""
+        return self._post(
+            "/api/v1/kavach/gate",
+            {
+                "command": command,
+                "tool_name": tool_name,
+                "session_id": session_id,
+                "dry_run": dry_run,
+            },
+        )
+
+    def health(self) -> Dict[str, Any]:
+        return self._get("/api/v1/kavach/health")
+
+    def state(self) -> Dict[str, Any]:
+        return self._get("/api/v1/kavach/state")
+
+    def audit(
+        self,
+        session_id: Optional[str] = None,
+        status: Optional[str] = None,
+        level: Optional[int] = None,
+        limit: int = 50,
+    ) -> Dict[str, Any]:
+        params: Dict[str, str] = {"limit": str(limit)}
+        if session_id:
+            params["session_id"] = session_id
+        if status:
+            params["status"] = status
+        if level is not None:
+            params["level"] = str(level)
+        return self._get("/api/v1/kavach/audit", params)
+
+
+class KavachGateCallback:
+    """LangChain callback handler that intercepts tool calls through the KAVACH DAN gate.
+
+    Drop-in: pass an instance in ``callbacks=[KavachGateCallback()]`` on any LangChain
+    agent or tool invocation. No agent code changes needed beyond adding the callback.
+
+    Usage::
+
+        from xshieldai_langchain import KavachGateCallback
+
+        callback = KavachGateCallback(
+            base_url="http://localhost:4850",
+            on_block="raise",       # or "warn"
+            dry_run=False,
+        )
+
+        result = agent.invoke({"input": "drop all backups"}, config={"callbacks": [callback]})
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:4850",
+        token: Optional[str] = None,
+        on_block: str = "raise",
+        dry_run: bool = False,
+        tool_name: str = "langchain",
+        session_id: Optional[str] = None,
+    ):
+        """
+        Args:
+            base_url: AEGIS server URL.
+            token: Bearer token (or set AEGIS_TOKEN env var).
+            on_block: ``"raise"`` (raise KavachGateError) or ``"warn"`` (print warning, continue).
+            dry_run: Classify only — no notification, no polling.
+            tool_name: Label appearing in audit records.
+            session_id: Audit grouping key. Auto-generated per callback instance if not set.
+        """
+        if on_block not in ("raise", "warn"):
+            raise ValueError("on_block must be 'raise' or 'warn'")
+        self.client = AegisClient(base_url=base_url, token=token)
+        self.on_block = on_block
+        self.dry_run = dry_run
+        self.tool_name = tool_name
+        self.session_id = session_id or f"lc-{uuid.uuid4().hex[:12]}"
+
+    # ---- LangChain BaseCallbackHandler interface (duck-typed) ----
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        tags: Optional[list] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Intercept tool invocation before execution — the correct KAVACH gate point."""
+        tool_name = serialized.get("name", self.tool_name) if serialized else self.tool_name
+        command = input_str if isinstance(input_str, str) else json.dumps(input_str)
+
+        try:
+            result = self.client.gate(
+                command=command,
+                tool_name=tool_name,
+                session_id=self.session_id,
+                dry_run=self.dry_run,
+            )
+        except RuntimeError as e:
+            # Aegis unreachable — fail open (log only) to avoid blocking all tooling
+            import warnings
+            warnings.warn(f"[KavachGateCallback] Aegis unreachable — proceeding unguarded: {e}", stacklevel=2)
+            return
+
+        if not result.get("allow", True):
+            level = result.get("level", 0)
+            reason = result.get("reason", "blocked")
+            approval_id = result.get("approval_id")
+
+            if self.on_block == "raise":
+                raise KavachGateError(command=command, level=level, reason=reason, approval_id=approval_id)
+            else:
+                import warnings
+                warnings.warn(
+                    f"[KavachGateCallback] KAVACH blocked DAN-{level}: {reason} — continuing (on_block=warn)",
+                    stacklevel=2,
+                )
+
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        pass  # post-execution hook — reserved for future telemetry
+
+    def on_tool_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        pass  # error path — no gate action needed

xshieldai_langchain-1.0.0/xshieldai_langchain.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: xshieldai-langchain
+Version: 1.0.0
+Summary: xShieldAI / AEGIS DAN gate callback for LangChain agents — pre-execution governance via @xshieldai/aegis
+Author-email: "Capt. Anil Sharma" <capt.anil.sharma@powerpbox.org>
+License: AGPL-3.0
+Project-URL: Homepage, https://xshieldai.com
+Project-URL: Repository, https://github.com/rocketlang/aegis/tree/main/packages/xshieldai-langchain
+Project-URL: Documentation, https://xshieldai.com/docs/langchain
+Keywords: langchain,xshieldai,aegis,ai-governance,agent-safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: langchain-core>=0.1.0; extra == "dev"
+
+# xshieldai-langchain
+
+KavachOS DAN gate callback for LangChain agents.
+
+Intercepts every tool call through the AEGIS KAVACH gate before execution.
+Zero agent code changes — add the callback and every tool invocation is governed.
+
+## Install
+
+```bash
+pip install xshieldai-langchain
+```
+
+## Quick start
+
+```python
+from xshieldai_langchain import KavachGateCallback
+
+callback = KavachGateCallback(
+    base_url="http://localhost:4850",   # AEGIS server
+    on_block="raise",                   # raise KavachGateError on DAN-3/4
+    dry_run=False,
+)
+
+# LangChain agent — pass callback in config
+result = agent.invoke(
+    {"input": "summarise the quarterly report"},
+    config={"callbacks": [callback]},
+)
+
+# Or attach to a single tool:
+result = my_tool.invoke("drop table users", config={"callbacks": [callback]})
+```
+
+## KavachGateCallback parameters
+
+| Parameter | Default | Description |
+|---|---|---|
+| `base_url` | `http://localhost:4850` | AEGIS server URL |
+| `token` | `$AEGIS_TOKEN` | Bearer auth token |
+| `on_block` | `"raise"` | `"raise"` → KavachGateError · `"warn"` → print + continue |
+| `dry_run` | `False` | Classify only — no notification, no human-in-loop polling |
+| `tool_name` | `"langchain"` | Label appearing in audit records |
+| `session_id` | auto-generated | Audit grouping key (one per agent session) |
+
+## Direct client
+
+```python
+from xshieldai_langchain import AegisClient
+
+client = AegisClient(base_url="http://localhost:4850")
+
+# Pre-flight budget check
+state = client.state()
+if state["budget"]["breached"]:
+    raise RuntimeError("Daily budget breached — halt")
+
+# Manual gate call
+result = client.gate(command="rm -rf /var/postgres", tool_name="my-agent")
+print(result)  # {"allow": false, "level": 4, "reason": "DAN-4 catastrophic..."}
+
+# Audit query
+records = client.audit(session_id="lc-abc123", status="stop", limit=20)
+```
+
+## How it works
+
+`KavachGateCallback.on_tool_start()` fires before any tool execution.
+It POSTs to `POST /api/v1/kavach/gate` on the AEGIS server.
+
+- **DAN-1/2**: allowed immediately, logged.
+- **DAN-3**: notify approver via Telegram/WhatsApp, wait for ALLOW/STOP.
+- **DAN-4**: blocked immediately, `KavachGateError` raised.
+
+All policy is in AEGIS — the callback is a thin HTTP relay.
+
+## AEGIS server
+
+Run with: `bun /root/aegis/src/dashboard/server.ts`  
+Default port: `4850`  
+Gate endpoint: `POST /api/v1/kavach/gate`
+
+## License
+
+AGPL-3.0 — see [LICENSE](../../LICENSE).

xshieldai_langchain-1.0.0/xshieldai_langchain.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+xshieldai_langchain/__init__.py
+xshieldai_langchain/gate.py
+xshieldai_langchain.egg-info/PKG-INFO
+xshieldai_langchain.egg-info/SOURCES.txt
+xshieldai_langchain.egg-info/dependency_links.txt
+xshieldai_langchain.egg-info/requires.txt
+xshieldai_langchain.egg-info/top_level.txt

xshieldai_langchain-1.0.0/xshieldai_langchain.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xshieldai_langchain-1.0.0/xshieldai_langchain.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[dev]
+pytest>=7
+langchain-core>=0.1.0
+
+[langchain]
+langchain-core>=0.1.0

xshieldai_langchain-1.0.0/xshieldai_langchain.egg-info/top_level.txt

@@ -0,0 +1 @@
+xshieldai_langchain