driftguard-ai 0.1.0__tar.gz

driftguard_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sujal maheshwari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

driftguard_ai-0.1.0/PKG-INFO

@@ -0,0 +1,496 @@
+Metadata-Version: 2.4
+Name: driftguard-ai
+Version: 0.1.0
+Summary: A semantic mistake-memory system for AI agents with MCP and in-process guardrail entrypoints.
+Author-email: Sujal Maheshwari <sujalmaheshwari07@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sujal-maheshwari2004/DriftGuard
+Project-URL: Repository, https://github.com/sujal-maheshwari2004/DriftGuard
+Project-URL: Issues, https://github.com/sujal-maheshwari2004/DriftGuard/issues
+Keywords: agents,mcp,memory,guardrails,retrieval,langgraph,agent-safety,ai-infrastructure
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: orjson>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: rich>=13.0
+Requires-Dist: sentence-transformers>=2.6
+Requires-Dist: spacy>=3.7
+Requires-Dist: sqlite-utils>=3.35
+Requires-Dist: tenacity>=8.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: demo
+Requires-Dist: langchain-openai>=0.3.0; extra == "demo"
+Requires-Dist: langgraph>=0.2.60; extra == "demo"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: langchain-openai>=0.3.0; extra == "dev"
+Requires-Dist: langgraph>=0.2.60; extra == "dev"
+Dynamic: license-file
+
+# DriftGuard
+
+**DriftGuard** is a semantic mistake-memory and guardrail layer for autonomous agents.
+
+It sits between **intent** and **execution**, allowing agents to learn from past failures and avoid repeating them.
+
+DriftGuard stores structured causal memories:
+
+```
+action → feedback → outcome
+```
+
+and surfaces warnings when similar risky actions appear again.
+
+It works with:
+
+* MCP agents
+* LangGraph workflows
+* custom Python agents
+* tool-calling planners
+* autonomous pipelines
+
+---
+
+## Why DriftGuard Exists
+
+Agents today can act.
+
+They usually cannot **remember mistakes meaningfully**.
+
+Typical failure loop:
+
+```
+agent makes mistake
+agent retries
+agent repeats mistake
+agent retries again
+```
+
+DriftGuard introduces a semantic failure memory layer:
+
+```
+plan step
+↓
+DriftGuard review
+↓
+warning surfaced
+↓
+agent revises action
+```
+
+This improves:
+
+* stability
+* reliability
+* convergence speed
+* evaluation consistency
+* production safety
+
+without requiring changes to your planner architecture.
+
+---
+
+## What DriftGuard Does
+
+DriftGuard provides:
+
+• semantic mistake memory
+• similarity-aware warning retrieval
+• policy-based execution guardrails
+• merge + deduplicate memory graphs
+• JSON or SQLite persistence
+• runtime metrics
+• pruning of stale weak memories
+• MCP server integration
+• LangGraph adapters
+• offline benchmark harness
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install driftguard
+```
+
+Install test dependencies:
+
+```bash
+pip install "driftguard[test]"
+```
+
+Install LangGraph demo dependencies:
+
+```bash
+pip install "driftguard[demo]"
+```
+
+Install the spaCy normalization model:
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+---
+
+## Quick Example (Python Agent)
+
+```python
+from driftguard import DriftGuard
+
+guard = DriftGuard()
+
+review = guard.before_step("increase salt")
+
+if review.warnings:
+    print(review.warnings[0].risk)
+
+guard.record(
+    action="increase salt",
+    feedback="too salty",
+    outcome="dish ruined",
+)
+```
+
+DriftGuard now remembers this failure and warns on similar steps later.
+
+---
+
+## Guard Policies
+
+Control how the agent reacts to detected risks:
+
+```python
+from driftguard import DriftGuard, DriftGuardSettings
+
+guard = DriftGuard(
+    settings=DriftGuardSettings(
+        guard_policy="acknowledge",
+        guard_min_confidence=0.8,
+    )
+)
+```
+
+Supported modes:
+
+| policy      | behavior                     |
+| ----------- | ---------------------------- |
+| warn        | surface warning only         |
+| block       | raise exception              |
+| acknowledge | require confirmation         |
+| record_only | store memory but skip review |
+
+---
+
+## MCP Server Usage
+
+Run DriftGuard as an MCP server:
+
+```bash
+driftguard-mcp
+```
+
+Available tools:
+
+```
+register_mistake
+query_memory
+deep_prune
+graph_stats
+guard_metrics
+```
+
+Example Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "driftguard": {
+      "command": "driftguard-mcp"
+    }
+  }
+}
+```
+
+---
+
+## LangGraph Integration
+
+Create a review node inside a LangGraph workflow:
+
+```python
+from driftguard import DriftGuard
+from driftguard import make_langgraph_review_node
+
+guard = DriftGuard()
+
+review_node = make_langgraph_review_node(guard)
+```
+
+Drop this node directly into a planner graph.
+
+---
+
+## Generic Payload Adapter
+
+Review arbitrary planner payloads:
+
+```python
+from driftguard import DriftGuard, review_payload
+
+guard = DriftGuard()
+
+result = review_payload(
+    guard,
+    {"action": "increase salt", "attempt": 2},
+)
+```
+
+---
+
+## CLI Benchmark Tool
+
+Evaluate merge and retrieval quality:
+
+```bash
+driftguard-benchmark
+```
+
+Export structured results:
+
+```bash
+driftguard-benchmark --format json
+```
+
+Measures:
+
+* merge precision
+* merge recall
+* retrieval precision
+* retrieval recall
+* F1 score
+
+---
+
+## Storage Model
+
+DriftGuard uses:
+
+```
+in-memory semantic graph runtime
++
+persistent storage backend
+```
+
+Supported persistence:
+
+| backend | purpose              |
+| ------- | -------------------- |
+| JSON    | local experiments    |
+| SQLite  | production workflows |
+
+Example configuration:
+
+```python
+from driftguard import DriftGuardSettings
+
+settings = DriftGuardSettings(
+    storage_backend="sqlite",
+    sqlite_filepath="driftguard.sqlite3",
+)
+```
+
+---
+
+## Metrics and Observability
+
+Runtime metrics available:
+
+```python
+from driftguard import build_runtime
+
+runtime = build_runtime()
+
+snapshot = runtime.metrics_snapshot()
+
+print(snapshot["counters"])
+```
+
+Includes:
+
+```
+reviews
+warnings
+blocks
+acknowledgements
+records
+node reuse
+edge reuse
+prune activity
+```
+
+Also available via MCP:
+
+```
+guard_metrics
+```
+
+---
+
+## Example Architecture Placement
+
+Typical agent loop:
+
+```
+planner
+ ↓
+candidate action
+ ↓
+DriftGuard review
+ ↓
+warning surfaced
+ ↓
+planner revision
+ ↓
+execution
+ ↓
+feedback recorded
+```
+
+DriftGuard improves stability without replacing the planner.
+
+---
+
+## Local Demos
+
+Two included demos:
+
+### Rule-based simulator
+
+Offline deterministic walkthrough:
+
+```bash
+python demo/rule_based/demo_agent.py
+```
+
+Shows:
+
+* merge behavior
+* warning retrieval
+* pruning cleanup
+* graph evolution
+
+---
+
+### LangGraph LLM agent demo
+
+```bash
+pip install "driftguard[demo]"
+python demo/langgraph/demo_agent.py
+```
+
+Demonstrates:
+
+planner → guard → revise → execute loop
+
+with real model interaction.
+
+---
+
+## CLI Entry Points
+
+Installed automatically:
+
+```
+driftguard-mcp
+driftguard-benchmark
+```
+
+---
+
+## Configuration Surface
+
+Example advanced setup:
+
+```python
+from driftguard import DriftGuardSettings
+
+settings = DriftGuardSettings(
+    retrieval_top_k=5,
+    retrieval_min_similarity=0.60,
+    similarity_threshold_action=0.72,
+    guard_policy="warn",
+)
+```
+
+Full configuration supports:
+
+```
+retrieval tuning
+similarity thresholds
+guard policy modes
+storage backend selection
+embedding configuration
+graph pruning controls
+logging verbosity
+```
+
+---
+
+## When To Use DriftGuard
+
+DriftGuard helps when your agent:
+
+* retries failing steps repeatedly
+* forgets past execution errors
+* needs execution-time guardrails
+* requires semantic mistake recall
+* runs multi-step planners
+* uses LangGraph or MCP
+* executes tools autonomously
+
+---
+
+## Project Status
+
+Current release includes:
+
+* semantic merge engine
+* similarity retrieval engine
+* graph persistence layer
+* SQLite backend
+* MCP server
+* LangGraph adapter
+* benchmark harness
+* runtime metrics
+* pruning engine
+* deterministic demo runtime
+* pytest coverage
+
+DriftGuard is suitable for early production experimentation and agent-infrastructure research workflows.
+
+---
+
+## License
+
+MIT License