Metadata-Version: 2.5
Name: alovia-watchdog
Version: 0.7.1
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
```

The core has no dependencies. Framework adapters are extras: `langchain`, `openai-agents`, `crewai`, `google-adk`, `agent-framework`, or `all`.

## 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 Watchdog can see across
# them. Without it each call is checked on its own, 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)
```

## Approvals

Some actions should wait for a person, such as a refund or an account change. Put those tools on the task's lease. Mint the lease on your deploy path with the deploy key and give it to the agent's client; every check that names a tool carries it.

```python
from alovia_watchdog import Watchdog, WatchdogBlocked

deploy = Watchdog(api_key=DEPLOY_KEY)
lease = deploy.mint_lease("support-bot", "ticket-4812", ttl_seconds=1800,
                          allowed_tools=["read_ticket", "refund"],
                          approval_required=["refund"],
                          amount_field="amount", approval_above=100)["lease"]

wd = Watchdog(api_key=RUNTIME_KEY, lease=lease)
v = wd.check("refund the order", agent="support-bot",
             tool_name="refund", tool_args={"ticket_id": "4812", "amount": 250})
if v.held:
    v = wd.wait_for_approval(v, timeout=600)
if v.enforce:
    raise WatchdogBlocked(v)
```

A refund of 100 or less runs without asking. A larger one, or one whose amount Watchdog cannot read, shows up in Review under Needs approval. `wait_for_approval` checks whether someone decided, every two seconds at first and less often the longer it waits; once approved it sends the same call again, and that one call goes through. A rejection, a closed approval window, or no decision before the timeout comes back as a block. A held call never runs on its own, even with `fail_mode="open"`. The framework integrations stop on a held call like on any block; call `wait_for_approval` yourself where you want to wait.

## 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
```

From 0.7.0 the model gets the inspected projection: hidden comments, invisible characters and encoded instructions are withheld, and a later call that uses a value from them is refused. Pass `source_kind`, `source` and `task_id` so findings name where the data came from, and `metadata` for a document's Title, Author, Subject and Keywords. Images are not read; pass the text you extracted.

