Skip to main content

alovia-watchdog

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

Install

pip install alovia-watchdog

Use

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).

You can also check directly:

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:

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:

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:

WatchdogToolMiddleware(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:

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

Metadata

Release files for alovia-watchdog 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alovia-watchdog 0.4.0
File Size Uploaded Provenance Actions
alovia_watchdog-0.4.0.tar.gz 30.6 kB Without provenance Details for alovia_watchdog-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alovia-watchdog 0.4.0
File Interpreter ABI Platform Actions
alovia_watchdog-0.4.0-py3-none-any.whl Python 3 none any Details for alovia_watchdog-0.4.0-py3-none-any.whl

Total release size: 53.2 kB

Release files / alovia_watchdog-0.4.0.tar.gz

Download URL alovia_watchdog-0.4.0.tar.gz
Size 30.6 kB
Tags Source
SHA-256 checksum
How to use checksums
72bd2d3c9e7cd37d29bd2afb8d4be385e4fca7c780fdcc23a5d9a0248c6fd7b5
BLAKE2b-256 checksum
How to use checksums
3341257401633e289357bce5e7a3f5bc842a1af76c3bfa78c0f86e9313d98d30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / alovia_watchdog-0.4.0-py3-none-any.whl

Download URL alovia_watchdog-0.4.0-py3-none-any.whl
Size 22.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aaa50d73514c4d5ab333f6cba7b72bd8691a39702e07d264f89b1255440b0a05
BLAKE2b-256 checksum
How to use checksums
ac0013a1fe7a35f877359e176e47dac21204b8d9c96ecd7a247896d4dbcb61d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for alovia-watchdog 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page