Metadata-Version: 2.5
Name: alovia-watchdog
Version: 0.5.0
Summary: Runtime protection for AI agents. Guard your agent's inputs with your Alovia fleet key.
Project-URL: Homepage, https://aloviaai.com
Author: Alovia
License: MIT
Keywords: agents,ai,guardrails,security,watchdog
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: agent-framework
Requires-Dist: agent-framework>=1.0; extra == 'agent-framework'
Provides-Extra: all
Requires-Dist: agent-framework>=1.0; extra == 'all'
Requires-Dist: crewai>=1.15.3; extra == 'all'
Requires-Dist: google-adk>=1.0; extra == 'all'
Requires-Dist: langchain>=1.0; extra == 'all'
Requires-Dist: openai-agents>=0.19; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=1.15.3; extra == 'crewai'
Provides-Extra: google-adk
Requires-Dist: google-adk>=1.0; extra == 'google-adk'
Provides-Extra: langchain
Requires-Dist: langchain>=1.0; extra == 'langchain'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.19; extra == 'openai-agents'
Description-Content-Type: text/markdown

# alovia-watchdog

Runtime protection for AI agents. Guard your agent's inputs with your Alovia fleet key.

## Install

```bash
pip install alovia-watchdog
```

## Use

```python
from alovia_watchdog import Watchdog, guard_input

wd = Watchdog(api_key="wd_live_...")

# Pass session_id: it groups a conversation's turns so the scope-expansion and
# cascade-anomaly detectors can see across them. Without it they have nothing to
# correlate and stay silent, so always send a stable per-conversation id.
@guard_input(wd, agent="support-bot", session_id=lambda: chat_id)
def handle(message):
    ...
```

`guard_input` raises `WatchdogBlocked` when `verdict.enforce` says to stop, so the wrapped function never runs on a malicious or unresolved input. On a network error it honors `fail_mode` (`"closed"` blocks, `"open"` allows).

### Fail mode

Leave `fail_mode` unset and the fail mode you set for the fleet in the dashboard decides an unresolved verdict on the server. Locally the client still stops on an unresolved verdict or a network error, the same as `"closed"`. Pass `fail_mode="open"` or `"closed"` only to override the fleet's setting for this client. Before 0.5.0 the client always sent `"closed"`, so the fleet's setting never applied to an SDK call.

Always pass `agent`. A call with no agent name has no mission to check against, so on a fleet that fails closed Watchdog refuses it with an `anonymous_actor` finding. This is a server rule: it applies to every SDK version, not only 0.5.0.

You can also check directly:

```python
verdict = wd.check("some user input", agent="support-bot", session_id=chat_id)
if verdict.enforce:
    ...
```

Use `verdict.enforce`, not `verdict.blocked`, to decide whether to stop. `enforce` answers "should I stop": it always stops on `block`, and it also honors `fail_mode` for `challenge` and `unknown`. `blocked` only answers "did the server say block", so code that checks `blocked` still lets `challenge` and `unknown` through even when `fail_mode` is `"closed"`.

## LangChain

Optional extra:

```bash
pip install alovia-watchdog[langchain]
```

`WatchdogToolMiddleware` gates every tool call through Watchdog before it runs, blocking off-mission or injected calls with a `ToolMessage` instead of letting the tool execute:

```python
from langchain.agents import create_agent
from alovia_watchdog import Watchdog
from alovia_watchdog.integrations.langchain import WatchdogToolMiddleware

wd = Watchdog(api_key="wd_live_...")

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[WatchdogToolMiddleware(wd, agent="support-bot", session_id=lambda: chat_id)],
)
```

For async agent graphs, the middleware also exposes `awrap_tool_call`, LangChain calls it automatically wherever the graph runs async.

### Checking tool results

Pass `inspect_results=True` and the middleware also checks what each tool returned before the model reads it. A result carrying an injected instruction is cleaned when it can be and withheld when it cannot:

```python
WatchdogToolMiddleware(wd, agent="support-bot", session_id=lambda: chat_id, inspect_results=True)
```

### Google ADK and Microsoft Agent Framework

The same result check is `after_tool_callback` (or `async_after_tool_callback`) in `alovia_watchdog.integrations.google_adk`, wired next to `before_tool_callback`, and `inspect_results=True` on `WatchdogFunctionMiddleware` in `alovia_watchdog.integrations.agent_framework`:

```python
LlmAgent(..., before_tool_callback=before_tool_callback(wd, agent="support-bot"),
         after_tool_callback=after_tool_callback(wd, agent="support-bot"))
WatchdogFunctionMiddleware(wd, agent="support-bot", session_id=lambda: chat_id, inspect_results=True)
```

## Any other framework

`guard_tool_call` and `guard_tool_result` wire Watchdog into any framework's own before-tool and after-tool points:

```python
from alovia_watchdog.integrations.hook import guard_tool_call, guard_tool_result

guard_tool_call(wd, name, args, agent="support-bot", session_id=chat_id)           # raises WatchdogBlocked to stop
text = guard_tool_result(wd, name, result, agent="support-bot", session_id=chat_id)  # hand `text` to the model
```

