Skip to main content

DriftShield Mini

Privacy-first, zero-infrastructure drift detection for AI agents.

Your LangChain agent just called the same API 47 times. Your CrewAI crew burned £200 in tokens overnight. Your research agent started writing marketing copy instead of financial summaries.

You didn't find out until morning.

DriftShield Mini catches this stuff in real-time.It wraps your existing agent, watches what it does, and pings you on Slack or Discord the moment something goes sideways. No dashboard. No cloud. No account to create. Just a local Python library running alongside your agent.

Installation

Install the updated v0.2.0 package via pip:

pip install driftshield-mini==0.2.0

To install with specific framework extras:

pip install "driftshield-mini[autogen,llama-index,langchain]"

What It Actually Does

DriftShield Mini monitors three core vectors:

  1. Loop Detection: Is your agent calling the same tool repeatedly or stuck in an infinite cycle (e.g., search → format → search → format)? DriftShield flags the pattern before it eats your budget.
  2. Goal Drift: Is your agent staying on task? DriftShield uses local CPU embeddings to measure how far the agent's recent outputs have drifted from its initial objective.
  3. Resource Spikes: Is a run burning significantly more tokens or runtime than normal? DriftShield learns baseline behavior and flags anomalous executions.

100% Local & Private: All traces go to a local SQLite database. Embeddings run on your CPU. Nothing leaves your machine except the alerts you explicitly direct to Slack or Discord.


Supported Frameworks (v0.2.0)

Import framework-specific wrappers using driftshield_mini:

from driftshield_mini import DriftMonitor                 # LangChain / manual API
from driftshield_mini.crewai import DriftCrew                 # CrewAI
from driftshield_mini.autogen import DriftAutogenAgent        # Microsoft AutoGen
from driftshield_mini.llama_index import DriftLlamaIndexHandler  # LlamaIndex
from driftshield_mini.openai_assistants import DriftOpenAIClient # OpenAI Assistants
from driftshield_mini.semantic_kernel import DriftKernelFilter   # Semantic Kernel
from driftshield_mini.haystack import DriftHaystackTracer        # Haystack
from driftshield_mini.google_adk import DriftADKCallbacks        # Google ADK

Quick Framework Examples

LangChain / Custom API

from driftshield_mini import DriftMonitor

monitor = DriftMonitor(
    agent_id="logistics-v2",
    alert_webhook="[https://hooks.slack.com/services/](https://hooks.slack.com/services/)...",
    goal_description="Optimise routing plans"
)

agent = monitor.wrap(existing_agent)
result = agent.invoke({"input": "optimise route for order #4821"})

CrewAI

from driftshield_mini.crewai import DriftCrew

crew = DriftCrew(
    crew=existing_crew,
    agent_id="research-team-v1",
    alert_webhook="[https://discord.com/api/webhooks/](https://discord.com/api/webhooks/)...",
)

result = crew.kickoff()

Microsoft AutoGen

monitored = DriftAutogenAgent(
    agent=assistant, 
    agent_id="autogen-analyst-v1",
    alert_webhook="[https://hooks.slack.com/](https://hooks.slack.com/)..."
)
user_proxy.initiate_chat(monitored.agent, message="Summarise Q3 results")

LlamaIndex

from llama_index.core.callbacks import CallbackManager
from llama_index.core import Settings

handler = DriftLlamaIndexHandler(agent_id="rag-agent-v1", goal_description="Answer policy questions")
Settings.callback_manager = CallbackManager([handler.callback_handler])

OpenAI Assistants

client = DriftOpenAIClient(openai.OpenAI(), agent_id="assistant-v1", goal_description="Process invoices")
client.run_assistant(thread_id=t.id, assistant_id=a.id)

Semantic Kernel

DriftKernelFilter(agent_id="sk-agent-v1", goal_description="Reconcile invoices").apply_to_kernel(kernel)

Haystack

DriftHaystackTracer(agent_id="haystack-v1").enable()   # Call once before running pipelines

Google ADK

drift = DriftADKCallbacks(agent_id="adk-v1")
agent = Agent(..., before_tool_callback=drift.before_tool, after_tool_callback=drift.after_tool)

How Calibration Works

For the first 30 runs (configurable), DriftShield quietly observes your agent to establish baseline averages for token consumption, execution times, and tool call sequences. No alerts are fired during this warm-up phase.

Once calibrated, it flags statistical anomalies. You can inspect your agent's baseline at any time:

driftshield baseline my-agent

Note: Even during initial calibration, DriftShield uses hard safety bounds to flag extreme loops (such as 50 identical sequential tool calls).


Sample Alert Payload

When drift is detected, structured payloads are dispatched to your configured webhook:

{
  "agent_id": "logistics-v2",
  "detector": "action_loop",
  "severity": "HIGH",
  "message": "Action loop: search_inventory called 6x in 45s",
  "suggested_action": "Check search_inventory input/output for stale data or error loops",
  "context": {
    "tool_name": "search_inventory",
    "repeat_count": 6,
    "recent_actions": ["search_inventory", "search_inventory", "search_inventory"]
  }
}

CLI Reference

Commands Overview

Command Description
alerts View recent drift alerts across agents.
baseline Show calculated baseline statistics for an agent.
download-model Download embedding models for offline/air-gapped execution.
export Export compliance logs formatted for regulatory frameworks (FCA / EU AI Act).
runs List recent execution runs for an agent.
traces View detailed trace logs for specific agent runs.

CLI Usage Examples

# View alerts triggered in the last 24 hours
driftshield alerts --last 24h

# Inspect execution traces for a specific run
driftshield traces logistics-v2 --run latest

# Export audit logs for compliance (CSV or JSON)
driftshield export --agent logistics-v2 --output audit.csv
driftshield export --agent logistics-v2 --output drift.json --drift-only --format json

# Pre-download embedding models for air-gapped environments
driftshield download-model

Detailed Configuration Options

Defaults are pre-tuned, but all parameters can be customized programmatically:

from driftshield_mini import DriftMonitor

monitor = DriftMonitor(
    agent_id="my-agent",
    alert_webhook="[https://hooks.slack.com/](https://hooks.slack.com/)...",
    goal_description="Summarise financial reports",
    calibration_runs=30,         # Runs before baseline detection activates
    loop_window=20,              # Number of recent actions inspected for loops
    loop_max_repeats=4,          # Repeated tool calls allowed before alerting
    similarity_threshold=0.5,    # Goal drift sensitivity (lower = stricter)
    spike_multiplier=2.5,        # Standard deviation multiplier for resource spikes
    min_alert_severity="MED",    # Minimum severity required to trigger webhooks
    alert_cooldown=60.0          # Seconds to wait before resending duplicate alerts
)

Programmatic Hooks

Attach custom event listeners to act on alerts programmatically:

def handle_drift(event):
    if event.severity.value == "CRITICAL":
        agent.stop()        # Terminate execution
        notify_oncall()     # Trigger on-call notification

monitor.on_drift(handle_drift)

Why I Built This

I kept hearing the same story: a developer builds an agent, it passes local tests, but runs wild overnight in production leaving them with a high API bill and a broken service. Complex observability platforms exist, but they often require hosted infrastructure, SaaS sign-ups, and dashboard overhead.

DriftShield Mini is designed as a minimal, lightweight utility to inform you when an agent strays off course, with zero external platform dependencies.


License

Distributed under the MIT License.


Metadata

Release files for driftshield-mini 0.2.1

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

Source distribution (sdist)

Source distribution for driftshield-mini 0.2.1
File Size Uploaded Provenance Actions
driftshield_mini-0.2.1.tar.gz 35.7 kB Without provenance Details for driftshield_mini-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for driftshield-mini 0.2.1
File Interpreter ABI Platform Actions
driftshield_mini-0.2.1-py3-none-any.whl Python 3 none any Details for driftshield_mini-0.2.1-py3-none-any.whl

Total release size: 77.0 kB

Release files / driftshield_mini-0.2.1.tar.gz

Download URL driftshield_mini-0.2.1.tar.gz
Size 35.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3760dccfa0309b4303afe96c00ee2ee42cffd97932bb7ee18d8413249a08e424
BLAKE2b-256 checksum
How to use checksums
21962ef70b1c70710be293c63e07b836bef18160b201544dd9de006051bc87d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / driftshield_mini-0.2.1-py3-none-any.whl

Download URL driftshield_mini-0.2.1-py3-none-any.whl
Size 41.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9b59a9936e8a10ca84e7ba4f5dbfa579f380993fc86d6532a7ada501e48ea8b5
BLAKE2b-256 checksum
How to use checksums
29f28ac301e1065a15436e292c72a3026d6b4bf8039cac5113cc54ad9dd10750
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for driftshield-mini 0.2.1

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