shieldpi 0.1.0__tar.gz

shieldpi-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: shieldpi
+Version: 0.1.0
+Summary: ShieldPi Watchtower — live agent monitoring SDK for Python
+Author-email: ShieldPi <support@shieldpi.io>
+License: Apache-2.0
+Project-URL: Homepage, https://shieldpi.io
+Project-URL: Documentation, https://docs.shieldpi.io/sdks/python
+Project-URL: Repository, https://github.com/ShieldPi1/shieldpi-watchtower
+Keywords: llm,security,agents,monitoring,ai-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# ShieldPi Python SDK
+
+Official Python SDK for the ShieldPi LLM Security Scanner API.
+
+## Installation
+
+```bash
+pip install shieldpi
+```
+
+## Quick Start
+
+```python
+from shieldpi import ShieldPi
+
+client = ShieldPi(api_key="your-api-key")
+
+# Create a target
+target = client.targets.create(
+    name="My Chatbot",
+    url="https://my-chatbot.com/api/chat",
+    scan_mode="api"
+)
+
+# Run a scan
+scan = client.scans.create(target_id=target.id)
+
+# Wait for completion
+result = client.scans.wait(scan.id)
+
+# Get the report
+print(f"Security Grade: {result.grade}")
+print(f"Score: {result.score}/100")
+print(f"Findings: {result.total_findings}")
+```
+
+## API Reference
+
+### Authentication
+```python
+client = ShieldPi(api_key="sk-...", base_url="https://api.shieldpi.io/api")
+```
+
+### Targets
+```python
+client.targets.list()
+client.targets.create(name="...", url="...", scan_mode="model")
+client.targets.get(target_id)
+client.targets.delete(target_id)
+```
+
+### Scans
+```python
+client.scans.create(target_id=target_id)
+client.scans.get(scan_id)
+client.scans.list()
+client.scans.wait(scan_id, timeout=3600)
+```
+
+### Reports
+```python
+client.scans.download_report(scan_id, format="pdf")
+client.scans.download_report(scan_id, format="json")
+```
+
+## Live Agent Monitoring
+
+For real-time agent monitoring, use the `Monitor` class:
+
+```python
+from shieldpi import Monitor
+
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitor.start_session(
+    agent_name="invoice-bot",
+    stated_goal="help users file invoices",
+) as session:
+    session.log_user_message("How do I file a Q1 invoice?")
+    session.log_tool_call("search_docs", {"query": "Q1 invoice filing"})
+    session.log_tool_result("search_docs", {"results": [...]})
+    session.log_final_response("Here's how to file a Q1 invoice...")
+```
+
+### LangChain Integration
+
+```python
+from shieldpi import Monitor
+from shieldpi.hooks.langchain import ShieldPiCallbackHandler
+
+monitor = Monitor(sdk_key="shpi_live_...")
+callbacks = [ShieldPiCallbackHandler(
+    monitor,
+    agent_name="my-agent",
+    stated_goal="help users with their accounts",
+)]
+
+agent.invoke({"input": "..."}, config={"callbacks": callbacks})
+```
+
+### Anthropic Tool Use
+
+```python
+from anthropic import Anthropic
+from shieldpi import Monitor
+from shieldpi.hooks.anthropic import monitored_tool_use
+
+anth = Anthropic()
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitored_tool_use(monitor, agent_name="invoice-bot") as session:
+    session.log_user_message("Help me file an invoice")
+    response = anth.messages.create(
+        model="claude-opus-4-20250514",
+        messages=[{"role": "user", "content": "Help me file an invoice"}],
+        tools=[...],
+    )
+    session.observe_anthropic_response(response)
+```
+
+## Configuration
+
+Environment variables:
+
+- `SHIELDPI_API_KEY` — API key for scanner operations
+- `SHIELDPI_SDK_KEY` — SDK key for live monitoring
+- `SHIELDPI_BASE_URL` — Override the API base URL (default: `https://api.shieldpi.io/api`)
+
+## License
+
+Apache-2.0

shieldpi-0.1.0/README.md

@@ -0,0 +1,131 @@
+# ShieldPi Python SDK
+
+Official Python SDK for the ShieldPi LLM Security Scanner API.
+
+## Installation
+
+```bash
+pip install shieldpi
+```
+
+## Quick Start
+
+```python
+from shieldpi import ShieldPi
+
+client = ShieldPi(api_key="your-api-key")
+
+# Create a target
+target = client.targets.create(
+    name="My Chatbot",
+    url="https://my-chatbot.com/api/chat",
+    scan_mode="api"
+)
+
+# Run a scan
+scan = client.scans.create(target_id=target.id)
+
+# Wait for completion
+result = client.scans.wait(scan.id)
+
+# Get the report
+print(f"Security Grade: {result.grade}")
+print(f"Score: {result.score}/100")
+print(f"Findings: {result.total_findings}")
+```
+
+## API Reference
+
+### Authentication
+```python
+client = ShieldPi(api_key="sk-...", base_url="https://api.shieldpi.io/api")
+```
+
+### Targets
+```python
+client.targets.list()
+client.targets.create(name="...", url="...", scan_mode="model")
+client.targets.get(target_id)
+client.targets.delete(target_id)
+```
+
+### Scans
+```python
+client.scans.create(target_id=target_id)
+client.scans.get(scan_id)
+client.scans.list()
+client.scans.wait(scan_id, timeout=3600)
+```
+
+### Reports
+```python
+client.scans.download_report(scan_id, format="pdf")
+client.scans.download_report(scan_id, format="json")
+```
+
+## Live Agent Monitoring
+
+For real-time agent monitoring, use the `Monitor` class:
+
+```python
+from shieldpi import Monitor
+
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitor.start_session(
+    agent_name="invoice-bot",
+    stated_goal="help users file invoices",
+) as session:
+    session.log_user_message("How do I file a Q1 invoice?")
+    session.log_tool_call("search_docs", {"query": "Q1 invoice filing"})
+    session.log_tool_result("search_docs", {"results": [...]})
+    session.log_final_response("Here's how to file a Q1 invoice...")
+```
+
+### LangChain Integration
+
+```python
+from shieldpi import Monitor
+from shieldpi.hooks.langchain import ShieldPiCallbackHandler
+
+monitor = Monitor(sdk_key="shpi_live_...")
+callbacks = [ShieldPiCallbackHandler(
+    monitor,
+    agent_name="my-agent",
+    stated_goal="help users with their accounts",
+)]
+
+agent.invoke({"input": "..."}, config={"callbacks": callbacks})
+```
+
+### Anthropic Tool Use
+
+```python
+from anthropic import Anthropic
+from shieldpi import Monitor
+from shieldpi.hooks.anthropic import monitored_tool_use
+
+anth = Anthropic()
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitored_tool_use(monitor, agent_name="invoice-bot") as session:
+    session.log_user_message("Help me file an invoice")
+    response = anth.messages.create(
+        model="claude-opus-4-20250514",
+        messages=[{"role": "user", "content": "Help me file an invoice"}],
+        tools=[...],
+    )
+    session.observe_anthropic_response(response)
+```
+
+## Configuration
+
+Environment variables:
+
+- `SHIELDPI_API_KEY` — API key for scanner operations
+- `SHIELDPI_SDK_KEY` — SDK key for live monitoring
+- `SHIELDPI_BASE_URL` — Override the API base URL (default: `https://api.shieldpi.io/api`)
+
+## License
+
+Apache-2.0

shieldpi-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shieldpi"
+version = "0.1.0"
+description = "ShieldPi Watchtower — live agent monitoring SDK for Python"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "ShieldPi", email = "support@shieldpi.io" }]
+keywords = ["llm", "security", "agents", "monitoring", "ai-security"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "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 :: Security",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+anthropic = ["anthropic>=0.25.0"]
+dev = ["pytest>=7", "pytest-asyncio>=0.21"]
+
+[project.urls]
+Homepage = "https://shieldpi.io"
+Documentation = "https://docs.shieldpi.io/sdks/python"
+Repository = "https://github.com/ShieldPi1/shieldpi-watchtower"
+
+[tool.setuptools.packages.find]
+where = ["src"]

shieldpi-0.1.0/setup.cfg

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

shieldpi-0.1.0/src/shieldpi/__init__.py

@@ -0,0 +1,41 @@
+"""ShieldPi Watchtower — Python SDK.
+
+Usage:
+
+    from shieldpi import Monitor
+
+    monitor = Monitor(sdk_key="shpi_live_...")
+    session = monitor.start_session(agent_name="invoice-bot", stated_goal="help users with invoices")
+
+    session.log_user_message("How do I file an invoice?")
+    session.log_tool_call("search_docs", {"query": "invoice filing"})
+    session.log_tool_result("search_docs", {"results": [...]})
+    session.log_final_response("Here's how to file an invoice...")
+
+    session.end()
+
+For LangChain:
+
+    from shieldpi import Monitor
+    from shieldpi.hooks.langchain import ShieldPiCallbackHandler
+
+    monitor = Monitor(sdk_key="shpi_live_...")
+    callbacks = [ShieldPiCallbackHandler(monitor, agent_name="my-agent")]
+
+    agent.run("...", callbacks=callbacks)
+
+For Anthropic tool use:
+
+    from shieldpi import Monitor
+    from shieldpi.hooks.anthropic import monitored_tool_use
+
+    monitor = Monitor(sdk_key="shpi_live_...")
+    with monitored_tool_use(monitor, agent_name="my-agent") as session:
+        result = anthropic_client.messages.create(...)
+        session.observe_anthropic_response(result)
+"""
+
+from shieldpi.client import Monitor, Session, ShieldPiError
+
+__version__ = "0.1.0"
+__all__ = ["Monitor", "Session", "ShieldPiError", "__version__"]

shieldpi-0.1.0/src/shieldpi/client.py

@@ -0,0 +1,322 @@
+"""ShieldPi SDK core — Monitor + Session objects.
+
+Design:
+- ``Monitor`` is created once with an SDK key and a base URL.
+- ``Session`` is created per agent conversation/task via ``monitor.start_session``.
+- Every ``log_*`` call fires an async HTTP POST that never blocks the agent.
+  Failures are caught, counted, and (optionally) raised via a ``raise_on_error``
+  flag. The default is silent failure — we never break production because a
+  monitoring call timed out.
+- Batching happens automatically for high-throughput agents via the
+  ``batch_size`` + ``flush_interval_s`` knobs on the ``Monitor``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import queue
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+try:
+    import httpx
+except ImportError as exc:  # pragma: no cover
+    raise RuntimeError(
+        "shieldpi requires httpx — install with `pip install shieldpi`"
+    ) from exc
+
+
+logger = logging.getLogger("shieldpi")
+
+
+class ShieldPiError(RuntimeError):
+    """Base class for SDK errors."""
+
+
+_DEFAULT_BASE_URL = "https://api.shieldpi.io/api/agent-monitor"
+_USER_AGENT = "shieldpi-python/0.1.0"
+
+
+# ── Event envelopes ─────────────────────────────────────────────────
+
+
+@dataclass
+class _QueuedEvent:
+    path: str  # "/event" or "/events/batch"
+    body: dict
+    session: "Session"
+
+
+# ── Monitor ─────────────────────────────────────────────────────────
+
+
+class Monitor:
+    """SDK entrypoint. One instance per process.
+
+    Args:
+        sdk_key: Your per-target SDK key. Starts with ``shpi_live_``.
+        base_url: Override the API base URL (defaults to prod).
+        raise_on_error: If True, ingest failures raise ``ShieldPiError``.
+            Default False — monitoring must never break the agent.
+        batch_size: Max events to buffer before flushing.
+        flush_interval_s: Max seconds between flushes.
+        timeout_s: HTTP timeout for each request.
+    """
+
+    def __init__(
+        self,
+        sdk_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        raise_on_error: bool = False,
+        batch_size: int = 20,
+        flush_interval_s: float = 1.0,
+        timeout_s: float = 5.0,
+    ) -> None:
+        self.sdk_key = sdk_key or os.environ.get("SHIELDPI_SDK_KEY", "")
+        if not self.sdk_key:
+            raise ShieldPiError(
+                "ShieldPi SDK key is required. Pass sdk_key= or set SHIELDPI_SDK_KEY"
+            )
+        self.base_url = (base_url or os.environ.get("SHIELDPI_BASE_URL") or _DEFAULT_BASE_URL).rstrip("/")
+        self.raise_on_error = raise_on_error
+        self.batch_size = max(1, batch_size)
+        self.flush_interval_s = max(0.1, flush_interval_s)
+        self.timeout_s = timeout_s
+
+        self._client = httpx.Client(
+            timeout=timeout_s,
+            headers={
+                "Authorization": f"Bearer {self.sdk_key}",
+                "User-Agent": _USER_AGENT,
+                "Content-Type": "application/json",
+            },
+        )
+        self._queue: queue.Queue[_QueuedEvent] = queue.Queue(maxsize=10_000)
+        self._shutdown = threading.Event()
+        self._worker = threading.Thread(
+            target=self._worker_loop, name="shieldpi-flusher", daemon=True
+        )
+        self._worker.start()
+        atexit.register(self.flush)
+        atexit.register(self.close)
+
+        # Counters
+        self.events_sent = 0
+        self.events_failed = 0
+
+    # ── Session API ────────────────────────────────────────────────
+
+    def start_session(
+        self,
+        *,
+        external_id: Optional[str] = None,
+        agent_name: Optional[str] = None,
+        framework: Optional[str] = None,
+        stated_goal: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> "Session":
+        """Create a new live monitoring session. Returns a Session object."""
+        body = {
+            "external_id": external_id,
+            "agent_name": agent_name,
+            "framework": framework,
+            "stated_goal": stated_goal,
+            "metadata": metadata,
+        }
+        try:
+            resp = self._client.post(f"{self.base_url}/session/start", json=body)
+            resp.raise_for_status()
+            data = resp.json()
+        except Exception as exc:
+            if self.raise_on_error:
+                raise ShieldPiError(f"start_session failed: {exc}") from exc
+            logger.warning("[shieldpi] start_session failed, returning offline session: %s", exc)
+            return Session(self, session_id="offline", offline=True)
+        return Session(self, session_id=data["session_id"])
+
+    # ── Ingest ─────────────────────────────────────────────────────
+
+    def _enqueue(self, session: "Session", body: dict) -> None:
+        try:
+            self._queue.put_nowait(_QueuedEvent(path="/event", body=body, session=session))
+        except queue.Full:
+            self.events_failed += 1
+            logger.warning("[shieldpi] event queue full — dropping event")
+
+    # ── Worker thread ──────────────────────────────────────────────
+
+    def _worker_loop(self) -> None:
+        buffer: list[_QueuedEvent] = []
+        last_flush = time.time()
+        while not self._shutdown.is_set():
+            try:
+                timeout = max(0.05, self.flush_interval_s - (time.time() - last_flush))
+                item = self._queue.get(timeout=timeout)
+                buffer.append(item)
+            except queue.Empty:
+                pass
+            now = time.time()
+            if buffer and (
+                len(buffer) >= self.batch_size
+                or (now - last_flush) >= self.flush_interval_s
+            ):
+                self._flush_buffer(buffer)
+                buffer.clear()
+                last_flush = now
+        # Final flush on shutdown
+        if buffer:
+            self._flush_buffer(buffer)
+
+    def _flush_buffer(self, buffer: list[_QueuedEvent]) -> None:
+        # Group by single vs batch. Right now everything goes in a batch call.
+        body = {"events": [ev.body for ev in buffer]}
+        try:
+            resp = self._client.post(f"{self.base_url}/events/batch", json=body)
+            if resp.status_code >= 400:
+                self.events_failed += len(buffer)
+                logger.warning("[shieldpi] batch ingest %d: %s", resp.status_code, resp.text[:200])
+                return
+            self.events_sent += len(buffer)
+        except Exception as exc:
+            self.events_failed += len(buffer)
+            if self.raise_on_error:
+                raise ShieldPiError(f"ingest failed: {exc}") from exc
+            logger.warning("[shieldpi] ingest failed: %s", exc)
+
+    def flush(self) -> None:
+        """Force-drain the queue. Called on atexit."""
+        deadline = time.time() + 5.0
+        while not self._queue.empty() and time.time() < deadline:
+            time.sleep(0.05)
+
+    def close(self) -> None:
+        self._shutdown.set()
+        try:
+            self._worker.join(timeout=2.0)
+        except Exception:
+            pass
+        try:
+            self._client.close()
+        except Exception:
+            pass
+
+
+# ── Session ─────────────────────────────────────────────────────────
+
+
+class Session:
+    """A live monitoring session for one agent conversation or task.
+
+    Call ``log_*`` methods for each step the agent takes. They never block.
+    Call ``end()`` when the session is over (or let atexit handle it).
+    """
+
+    def __init__(self, monitor: Monitor, session_id: str, *, offline: bool = False) -> None:
+        self._monitor = monitor
+        self.session_id = session_id
+        self._offline = offline
+
+    # ── log_* helpers ──────────────────────────────────────────────
+
+    def log_user_message(self, content: str, *, metadata: Optional[dict] = None) -> None:
+        self._enqueue("user_message", content=content, actor="user", metadata=metadata)
+
+    def log_llm_call(self, content: str, *, metadata: Optional[dict] = None) -> None:
+        self._enqueue("llm_call", content=content, actor="assistant", metadata=metadata)
+
+    def log_final_response(self, content: str, *, metadata: Optional[dict] = None) -> None:
+        self._enqueue("final_response", content=content, actor="assistant", metadata=metadata)
+
+    def log_tool_call(
+        self,
+        tool_name: str,
+        tool_args: Optional[dict] = None,
+        *,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        self._enqueue(
+            "tool_call",
+            tool_name=tool_name,
+            tool_args=tool_args,
+            actor="assistant",
+            metadata=metadata,
+        )
+
+    def log_tool_result(
+        self,
+        tool_name: str,
+        tool_result: Any,
+        *,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        if tool_result is not None and not isinstance(tool_result, dict):
+            tool_result = {"value": tool_result}
+        self._enqueue(
+            "tool_result",
+            tool_name=tool_name,
+            tool_result=tool_result,
+            actor="tool",
+            metadata=metadata,
+        )
+
+    def log_memory_write(
+        self,
+        memory_key: str,
+        memory_value: str,
+        *,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        self._enqueue(
+            "memory_write",
+            memory_key=memory_key,
+            memory_value=memory_value,
+            actor="system",
+            metadata=metadata,
+        )
+
+    def log_memory_read(
+        self,
+        memory_key: str,
+        *,
+        metadata: Optional[dict] = None,
+    ) -> None:
+        self._enqueue("memory_read", memory_key=memory_key, actor="system", metadata=metadata)
+
+    def log_error(self, message: str, *, metadata: Optional[dict] = None) -> None:
+        self._enqueue("error", content=message, actor="system", metadata=metadata)
+
+    def end(self, status: str = "ended") -> None:
+        if self._offline:
+            return
+        try:
+            resp = self._monitor._client.post(
+                f"{self._monitor.base_url}/session/end",
+                json={"session_id": self.session_id, "status": status},
+            )
+            resp.raise_for_status()
+        except Exception as exc:
+            if self._monitor.raise_on_error:
+                raise ShieldPiError(f"end_session failed: {exc}") from exc
+            logger.warning("[shieldpi] end_session failed: %s", exc)
+
+    # ── Internal ───────────────────────────────────────────────────
+
+    def _enqueue(self, event_type: str, **fields) -> None:
+        if self._offline:
+            return
+        body: dict[str, Any] = {"session_id": self.session_id, "event_type": event_type}
+        for k, v in fields.items():
+            if v is not None:
+                body[k] = v
+        self._monitor._enqueue(self, body)
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.end(status="ended" if exc_type is None else "abandoned")

shieldpi-0.1.0/src/shieldpi/hooks/__init__.py

@@ -0,0 +1 @@
+"""Framework-specific instrumentation hooks for the ShieldPi SDK."""

shieldpi-0.1.0/src/shieldpi/hooks/anthropic.py

@@ -0,0 +1,89 @@
+"""Anthropic tool-use instrumentation for ShieldPi.
+
+Wraps the Anthropic Python SDK messages.create call so every tool_use block
+and subsequent tool_result is logged to a ShieldPi session.
+
+Usage:
+
+    from anthropic import Anthropic
+    from shieldpi import Monitor
+    from shieldpi.hooks.anthropic import monitored_tool_use
+
+    anth = Anthropic()
+    monitor = Monitor(sdk_key="shpi_live_...")
+
+    with monitored_tool_use(monitor, agent_name="invoice-bot") as session:
+        session.log_user_message("Help me file an invoice")
+        response = anth.messages.create(
+            model="claude-opus-4-20250514",
+            messages=[{"role": "user", "content": "Help me file an invoice"}],
+            tools=[...],
+        )
+        session.observe_anthropic_response(response)
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from typing import Any, Iterator, Optional
+
+from shieldpi.client import Monitor, Session
+
+logger = logging.getLogger("shieldpi.anthropic")
+
+
+class _AnthropicAwareSession:
+    """Thin wrapper that adds ``observe_anthropic_response`` to a Session."""
+
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._session, name)
+
+    def observe_anthropic_response(self, response: Any) -> None:
+        """Walk an Anthropic messages.create response and emit events."""
+        try:
+            blocks = getattr(response, "content", None) or []
+            for block in blocks:
+                btype = getattr(block, "type", None) or (block.get("type") if isinstance(block, dict) else None)
+                if btype == "text":
+                    text = getattr(block, "text", None) or (block.get("text") if isinstance(block, dict) else "")
+                    if text:
+                        self._session.log_llm_call(text[:4000])
+                elif btype == "tool_use":
+                    name = getattr(block, "name", None) or (block.get("name") if isinstance(block, dict) else "unknown_tool")
+                    args = getattr(block, "input", None) or (block.get("input") if isinstance(block, dict) else {}) or {}
+                    if not isinstance(args, dict):
+                        args = {"input": str(args)}
+                    self._session.log_tool_call(name, args)
+        except Exception as exc:
+            logger.warning("[shieldpi.anthropic] observe_anthropic_response failed: %s", exc)
+
+    def observe_tool_result(self, tool_name: str, result: Any) -> None:
+        """Call this after you execute a tool_use block locally."""
+        self._session.log_tool_result(tool_name, result)
+
+
+@contextmanager
+def monitored_tool_use(
+    monitor: Monitor,
+    *,
+    agent_name: Optional[str] = None,
+    stated_goal: Optional[str] = None,
+    external_id: Optional[str] = None,
+) -> Iterator[_AnthropicAwareSession]:
+    session = monitor.start_session(
+        external_id=external_id,
+        agent_name=agent_name,
+        framework="anthropic",
+        stated_goal=stated_goal,
+    )
+    wrapper = _AnthropicAwareSession(session)
+    try:
+        yield wrapper
+        session.end(status="ended")
+    except BaseException:
+        session.end(status="abandoned")
+        raise

shieldpi-0.1.0/src/shieldpi/hooks/langchain.py

@@ -0,0 +1,234 @@
+"""LangChain callback handler for ShieldPi.
+
+Usage:
+
+    from shieldpi import Monitor
+    from shieldpi.hooks.langchain import ShieldPiCallbackHandler
+
+    monitor = Monitor(sdk_key="shpi_live_...")
+    handler = ShieldPiCallbackHandler(
+        monitor,
+        agent_name="invoice-bot",
+        stated_goal="help users file invoices",
+    )
+
+    agent.invoke({"input": "..."}, config={"callbacks": [handler]})
+
+The handler creates one Session per chain run. It hooks into every LangChain
+event (chat model start/end, tool start/end, agent action, agent finish) and
+translates each into a ShieldPi event.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+from uuid import UUID
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+except ImportError as exc:  # pragma: no cover
+    raise RuntimeError(
+        "shieldpi[langchain] requires langchain-core — install with "
+        "`pip install shieldpi[langchain]`"
+    ) from exc
+
+from shieldpi.client import Monitor, Session
+
+logger = logging.getLogger("shieldpi.langchain")
+
+
+class ShieldPiCallbackHandler(BaseCallbackHandler):
+    """Instruments a LangChain run with a ShieldPi live monitoring session."""
+
+    def __init__(
+        self,
+        monitor: Monitor,
+        *,
+        agent_name: Optional[str] = None,
+        stated_goal: Optional[str] = None,
+        framework: str = "langchain",
+        external_id: Optional[str] = None,
+    ) -> None:
+        self.monitor = monitor
+        self.agent_name = agent_name
+        self.stated_goal = stated_goal
+        self.framework = framework
+        self.external_id = external_id
+        self._sessions: dict[UUID, Session] = {}
+
+    # ── Root run lifecycle ─────────────────────────────────────────
+
+    def _ensure_session(self, run_id: UUID) -> Session:
+        if run_id in self._sessions:
+            return self._sessions[run_id]
+        session = self.monitor.start_session(
+            external_id=self.external_id or str(run_id),
+            agent_name=self.agent_name,
+            framework=self.framework,
+            stated_goal=self.stated_goal,
+        )
+        self._sessions[run_id] = session
+        return session
+
+    def _finish_session(self, run_id: UUID, status: str = "ended") -> None:
+        session = self._sessions.pop(run_id, None)
+        if session is not None:
+            try:
+                session.end(status=status)
+            except Exception:
+                logger.warning("[shieldpi.langchain] end_session failed", exc_info=True)
+
+    # ── LangChain callbacks ────────────────────────────────────────
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any],
+        inputs: dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        if parent_run_id is not None:
+            return  # only the root chain creates a session
+        session = self._ensure_session(run_id)
+        user_input = inputs.get("input") or inputs.get("question") or str(inputs)
+        if isinstance(user_input, str) and user_input:
+            session.log_user_message(user_input)
+
+    def on_chain_end(
+        self,
+        outputs: dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        if parent_run_id is not None:
+            return
+        session = self._sessions.get(run_id)
+        if session is not None:
+            output = outputs.get("output") or outputs.get("answer") or str(outputs)
+            if isinstance(output, str) and output:
+                session.log_final_response(output)
+        self._finish_session(run_id, status="ended")
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        if parent_run_id is not None:
+            return
+        session = self._sessions.get(run_id)
+        if session is not None:
+            session.log_error(str(error))
+        self._finish_session(run_id, status="abandoned")
+
+    # ── LLM calls ──────────────────────────────────────────────────
+
+    def on_llm_start(
+        self,
+        serialized: dict[str, Any],
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        root = self._root_run_id(run_id, parent_run_id)
+        session = self._sessions.get(root)
+        if session is None:
+            return
+        for prompt in prompts:
+            session.log_llm_call(prompt[:4000])
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        root = self._root_run_id(run_id, parent_run_id)
+        session = self._sessions.get(root)
+        if session is None:
+            return
+        for batch in messages:
+            for m in batch:
+                content = getattr(m, "content", None) or str(m)
+                if isinstance(content, str) and content:
+                    session.log_llm_call(content[:4000])
+
+    # ── Tool calls ─────────────────────────────────────────────────
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        root = self._root_run_id(run_id, parent_run_id)
+        session = self._sessions.get(root)
+        if session is None:
+            return
+        tool_name = (serialized or {}).get("name") or "unknown_tool"
+        args = kwargs.get("inputs") or {"input": input_str}
+        if not isinstance(args, dict):
+            args = {"input": str(args)}
+        session.log_tool_call(tool_name, args)
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        root = self._root_run_id(run_id, parent_run_id)
+        session = self._sessions.get(root)
+        if session is None:
+            return
+        tool_name = kwargs.get("name") or "unknown_tool"
+        session.log_tool_result(tool_name, output)
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        root = self._root_run_id(run_id, parent_run_id)
+        session = self._sessions.get(root)
+        if session is None:
+            return
+        session.log_error(f"Tool error: {error}")
+
+    # ── Helpers ────────────────────────────────────────────────────
+
+    def _root_run_id(self, run_id: UUID, parent_run_id: Optional[UUID]) -> UUID:
+        """Find the root run that owns the Session. LangChain nests runs;
+        we attach the Session to the outermost chain run_id only."""
+        # Simple heuristic: if run_id is a known session, use it; otherwise
+        # fall back to parent_run_id. Deeply nested agents may skip this and
+        # that's acceptable — events just drop silently for non-root runs.
+        if run_id in self._sessions:
+            return run_id
+        if parent_run_id is not None and parent_run_id in self._sessions:
+            return parent_run_id
+        # Last resort: attach to any active session
+        if self._sessions:
+            return next(iter(self._sessions.keys()))
+        return run_id

shieldpi-0.1.0/src/shieldpi.egg-info/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: shieldpi
+Version: 0.1.0
+Summary: ShieldPi Watchtower — live agent monitoring SDK for Python
+Author-email: ShieldPi <support@shieldpi.io>
+License: Apache-2.0
+Project-URL: Homepage, https://shieldpi.io
+Project-URL: Documentation, https://docs.shieldpi.io/sdks/python
+Project-URL: Repository, https://github.com/ShieldPi1/shieldpi-watchtower
+Keywords: llm,security,agents,monitoring,ai-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+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 :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# ShieldPi Python SDK
+
+Official Python SDK for the ShieldPi LLM Security Scanner API.
+
+## Installation
+
+```bash
+pip install shieldpi
+```
+
+## Quick Start
+
+```python
+from shieldpi import ShieldPi
+
+client = ShieldPi(api_key="your-api-key")
+
+# Create a target
+target = client.targets.create(
+    name="My Chatbot",
+    url="https://my-chatbot.com/api/chat",
+    scan_mode="api"
+)
+
+# Run a scan
+scan = client.scans.create(target_id=target.id)
+
+# Wait for completion
+result = client.scans.wait(scan.id)
+
+# Get the report
+print(f"Security Grade: {result.grade}")
+print(f"Score: {result.score}/100")
+print(f"Findings: {result.total_findings}")
+```
+
+## API Reference
+
+### Authentication
+```python
+client = ShieldPi(api_key="sk-...", base_url="https://api.shieldpi.io/api")
+```
+
+### Targets
+```python
+client.targets.list()
+client.targets.create(name="...", url="...", scan_mode="model")
+client.targets.get(target_id)
+client.targets.delete(target_id)
+```
+
+### Scans
+```python
+client.scans.create(target_id=target_id)
+client.scans.get(scan_id)
+client.scans.list()
+client.scans.wait(scan_id, timeout=3600)
+```
+
+### Reports
+```python
+client.scans.download_report(scan_id, format="pdf")
+client.scans.download_report(scan_id, format="json")
+```
+
+## Live Agent Monitoring
+
+For real-time agent monitoring, use the `Monitor` class:
+
+```python
+from shieldpi import Monitor
+
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitor.start_session(
+    agent_name="invoice-bot",
+    stated_goal="help users file invoices",
+) as session:
+    session.log_user_message("How do I file a Q1 invoice?")
+    session.log_tool_call("search_docs", {"query": "Q1 invoice filing"})
+    session.log_tool_result("search_docs", {"results": [...]})
+    session.log_final_response("Here's how to file a Q1 invoice...")
+```
+
+### LangChain Integration
+
+```python
+from shieldpi import Monitor
+from shieldpi.hooks.langchain import ShieldPiCallbackHandler
+
+monitor = Monitor(sdk_key="shpi_live_...")
+callbacks = [ShieldPiCallbackHandler(
+    monitor,
+    agent_name="my-agent",
+    stated_goal="help users with their accounts",
+)]
+
+agent.invoke({"input": "..."}, config={"callbacks": callbacks})
+```
+
+### Anthropic Tool Use
+
+```python
+from anthropic import Anthropic
+from shieldpi import Monitor
+from shieldpi.hooks.anthropic import monitored_tool_use
+
+anth = Anthropic()
+monitor = Monitor(sdk_key="shpi_live_...")
+
+with monitored_tool_use(monitor, agent_name="invoice-bot") as session:
+    session.log_user_message("Help me file an invoice")
+    response = anth.messages.create(
+        model="claude-opus-4-20250514",
+        messages=[{"role": "user", "content": "Help me file an invoice"}],
+        tools=[...],
+    )
+    session.observe_anthropic_response(response)
+```
+
+## Configuration
+
+Environment variables:
+
+- `SHIELDPI_API_KEY` — API key for scanner operations
+- `SHIELDPI_SDK_KEY` — SDK key for live monitoring
+- `SHIELDPI_BASE_URL` — Override the API base URL (default: `https://api.shieldpi.io/api`)
+
+## License
+
+Apache-2.0

shieldpi-0.1.0/src/shieldpi.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/shieldpi/__init__.py
+src/shieldpi/client.py
+src/shieldpi.egg-info/PKG-INFO
+src/shieldpi.egg-info/SOURCES.txt
+src/shieldpi.egg-info/dependency_links.txt
+src/shieldpi.egg-info/requires.txt
+src/shieldpi.egg-info/top_level.txt
+src/shieldpi/hooks/__init__.py
+src/shieldpi/hooks/anthropic.py
+src/shieldpi/hooks/langchain.py

shieldpi-0.1.0/src/shieldpi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shieldpi-0.1.0/src/shieldpi.egg-info/requires.txt

@@ -0,0 +1,11 @@
+httpx>=0.24.0
+
+[anthropic]
+anthropic>=0.25.0
+
+[dev]
+pytest>=7
+pytest-asyncio>=0.21
+
+[langchain]
+langchain-core>=0.1.0

shieldpi-0.1.0/src/shieldpi.egg-info/top_level.txt

@@ -0,0 +1 @@
+shieldpi