longguard 0.1.1__tar.gz

longguard-0.1.1/.github/release.yml

@@ -0,0 +1,20 @@
+changelog:
+  categories:
+    - title: "🚀 Features & Enhancements"
+      labels:
+        - "enhancement"
+        - "feature"
+    - title: "🐛 Bug Fixes"
+      labels:
+        - "bug"
+        - "fix"
+    - title: "📝 Documentation"
+      labels:
+        - "documentation"
+        - "docs"
+    - title: "🧰 Maintenance & CI"
+      labels:
+        - "maintenance"
+        - "ci"
+        - "dependencies"
+        - "chore"

longguard-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --python ${{ matrix.python-version }} --extra dev
+
+      - name: Run Ruff Linter & Formatter
+        run: |
+          uv run --python ${{ matrix.python-version }} ruff check src/ tests/
+
+      - name: Run MyPy Type Checker
+        run: |
+          uv run --python ${{ matrix.python-version }} mypy src/
+
+      - name: Run Pytest Suite with Coverage
+        run: |
+          uv run --python ${{ matrix.python-version }} pytest tests/ --cov=longguard --cov-report=xml --cov-report=term-missing
+
+      - name: Verify Package Build
+        run: |
+          uv build

longguard-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install documentation dependencies
+        run: uv sync --extra docs
+
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

longguard-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    name: Build and Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run Test Suite
+        run: uv run pytest tests/ -v
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: false

longguard-0.1.1/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Linter and type-checker caches
+.ruff_cache/
+.mypy_cache/
+
+# OS artifacts
+.DS_Store
+Thumbs.db
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment variables & secrets
+.env
+.env.*
+*.local
+
+# Documentation build output
+site/
+

longguard-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing to LongGuard
+
+Thank you for your interest in contributing to **LongGuard**! We welcome bug reports, feature requests, documentation improvements, and pull requests.
+
+LongGuard is an open-source project by [EnDevSols](https://github.com/ENDEVSOLS).
+
+---
+
+## Development Setup
+
+LongGuard uses [`uv`](https://github.com/astral-sh/uv) for fast and deterministic Python environment management.
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/ENDEVSOLS/LongGuard.git
+cd LongGuard
+```
+
+### 2. Install dependencies
+
+```bash
+# Install package with all dev dependencies
+uv sync --extra dev
+```
+
+### 3. Run Tests
+
+```bash
+# Run all unit tests
+uv run pytest tests/ -v
+
+# Run with test coverage
+uv run pytest tests/ --cov=longguard --cov-report=term-missing
+```
+
+### 4. Code Quality Checks
+
+We enforce formatting and linting with **Ruff** and strict static typing with **MyPy**:
+
+```bash
+# Run linter
+uv run ruff check src/ tests/
+
+# Run type checker
+uv run mypy src/
+```
+
+Ensure all tests, lint checks, and type checks pass before submitting a Pull Request.
+
+---
+
+## Pull Request Guidelines
+
+1. **Focus on solving real agent failure modes**: If adding a new detector, provide synthetic or real-world traces in `tests/` demonstrating both positive detection and non-interference on legitimate tasks.
+2. **Keep overhead minimal**: Loop detection runs synchronously on each agent step; algorithms should execute in sub-millisecond time.
+3. **Preserve framework neutrality**: Core detection mechanisms (`src/longguard/core/`) must remain independent of specific agent frameworks (LangGraph, LangChain, etc.). Framework integrations belong in `src/longguard/integrations/`.
+4. **Follow Semantic Versioning**: Major for breaking changes, minor for new detectors/adapters, patch for bug fixes.
+
+---
+
+## License
+
+By contributing to LongGuard, you agree that your contributions will be licensed under the [MIT License](LICENSE).

longguard-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EnDevSols
+
+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.

longguard-0.1.1/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.5
+Name: longguard
+Version: 0.1.1
+Summary: Circuit breaker middleware for LangGraph/LangChain agents — detect loops, inject Reflect & Pivot, prevent runaway costs
+Project-URL: Homepage, https://github.com/ENDEVSOLS/LongGuard
+Project-URL: Repository, https://github.com/ENDEVSOLS/LongGuard
+Project-URL: Issues, https://github.com/ENDEVSOLS/LongGuard/issues
+Project-URL: Documentation, https://github.com/ENDEVSOLS/LongGuard#readme
+Author-email: EnDevSols <info@endevsols.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,circuit-breaker,cost-control,langchain,langgraph,llm,loop-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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.10
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=1.0.0; extra == 'all'
+Requires-Dist: langchain>=1.0.0; extra == 'all'
+Requires-Dist: langgraph>=1.0.0; extra == 'all'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5.0; extra == 'all'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'all'
+Requires-Dist: sentence-transformers>=2.7.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.7.0; extra == 'embeddings'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.0.0; extra == 'langchain'
+Requires-Dist: langchain>=1.0.0; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=1.0.0; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# LongGuard 🛡️
+
+**In-Flight Circuit Breaker & Reasoning Loop Recovery for AI Agents**
+
+*Stop runaway agent loops, prevent token budget blowouts, and inject "Reflect & Pivot" guidance before crashes happen.*
+
+[![CI](https://github.com/ENDEVSOLS/LongGuard/actions/workflows/ci.yml/badge.svg)](https://github.com/ENDEVSOLS/LongGuard/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://endevsols.github.io/LongGuard/)
+[![PyPI version](https://img.shields.io/pypi/v/longguard.svg?color=blue)](https://pypi.org/project/longguard/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![LangGraph](https://img.shields.io/badge/LangGraph-1.0%2B-orange.svg)](https://github.com/langchain-ai/langgraph)
+[![LangChain](https://img.shields.io/badge/LangChain-1.0%2B-green.svg)](https://github.com/langchain-ai/langchain)
+
+[**Read Documentation**](https://endevsols.github.io/LongGuard/) • [**Report Bug**](https://github.com/ENDEVSOLS/LongGuard/issues) • [**EnDevSols AI Suite**](https://github.com/ENDEVSOLS)
+
+</div>
+
+---
+
+## ⚡ What is LongGuard?
+
+When autonomous LLM agents (LangGraph, LangChain, or custom loops) hit an unexpected hurdle, they often **get stuck in repetitive reasoning loops**:
+- Calling the exact same tool with the exact same parameters over and over.
+- Spinning between two reasoning thoughts (semantic oscillation).
+- Aimlessly wandering with zero progress while burning thousands of tokens.
+
+Frameworks like LangGraph have a built-in `recursion_limit`, but it is a **hard crash** (`GraphRecursionError`) that drops state, fails the user request, and provides zero opportunity for recovery.
+
+**LongGuard is an intelligent circuit breaker middleware.** It monitors your agent's chain-of-thought in real time, catches loops early, injects a **"Reflect & Pivot"** prompt to guide the agent back on track, and only terminates gracefully if recovery fails.
+
+```
+                  ┌─────────────────────────────────┐
+                  │      Agent Execution Loop       │
+                  └────────────────┬────────────────┘
+                                   │  Step N
+                                   ▼
+                        ┌─────────────────────┐
+                        │   LongGuard Hook    │
+                        └──────────┬──────────┘
+                                   │
+               ┌───────────────────┴───────────────────┐
+               ▼                                       ▼
+     [ No Loop Detected ]                     [ Loop Detected! ]
+               │                                       │
+        State: CLOSED                                  ▼
+      (Normal execution)                      State: REFLECTING
+                                                       │
+                                            Inject "Reflect & Pivot"
+                                            Prompt into Context
+                                                       │
+                                         ┌─────────────┴─────────────┐
+                                         ▼                           ▼
+                                    [ Recovers ]              [ Still Stuck ]
+                                         │                           │
+                                   State: CLOSED               State: OPEN
+                                   (Runs to end)            (Graceful Termination)
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+
+```bash
+# Core package (zero heavy dependencies)
+pip install longguard
+
+# With LangGraph integration
+pip install longguard[langgraph]
+
+# With LangChain integration
+pip install longguard[langchain]
+```
+
+### 2. LangGraph Integration (1 Line)
+
+Compatible with **LangGraph 1.0+** and modern multimodal models (Claude, Gemini, OpenAI):
+
+```python
+from langgraph.graph import StateGraph
+from longguard.integrations.langgraph import add_guard_to_graph
+from longguard import GuardConfig
+
+# 1. Define your standard LangGraph workflow
+workflow = StateGraph(AgentState)
+workflow.add_node("agent", agent_node)
+workflow.add_node("tools", tool_node)
+workflow.add_edge("agent", "tools")
+workflow.add_conditional_edges("tools", should_continue)
+
+# 2. Wrap with LongGuard — that's it!
+workflow = add_guard_to_graph(workflow, GuardConfig())
+app = workflow.compile()
+
+# 3. Access execution analytics after the run
+guard = workflow.__longguard__
+print(guard.get_report().summary())
+```
+
+### 3. Standalone / Custom Agent Loop
+
+If you run a custom `while` loop or proprietary agent orchestrator:
+
+```python
+from longguard import CircuitBreaker, GuardConfig, AgentStep
+
+breaker = CircuitBreaker(GuardConfig(
+    tool_repeat_threshold=3,    # 3 identical tool calls = trigger
+    max_tokens_per_run=50_000,  # Hard token cap
+))
+
+for step in run_agent():
+    decision = breaker.check(AgentStep(
+        step_number=step.index,
+        thought=step.thought,
+        action=step.tool_name,
+        action_input=step.arguments,
+        observation=step.tool_output,
+        tokens_used=step.tokens,
+    ))
+
+    if decision.action == "reflect":
+        # Inject the recovery advice into your agent's message list
+        messages.append({"role": "user", "content": decision.inject_prompt})
+    elif decision.action == "kill":
+        print(f"Halted safely: {decision.reason}")
+        break
+
+# View summary report
+print(breaker.report.summary())
+```
+
+---
+
+## 🔍 The 4 Loop Detectors
+
+LongGuard runs four lightweight detectors concurrently at every step:
+
+| Detector | What It Catches | Real-World Example |
+|---|---|---|
+| **Tool Repeat** | Calling the same tool with identical inputs $\ge N$ times | Agent calls `web_search("apple stock 2026")` 4 times with zero param changes |
+| **Semantic Oscillation** | Cycling between the same concepts in thoughts | Agent reasons "I should search A", then "No, B", then "Actually A", then "No, B" |
+| **Dead-End Drift** | Zero new information or observations for 5+ steps | Agent makes queries that return blank results or repetitive error strings |
+| **Token Velocity** | Sudden exponential token spikes per step | Agent dumps huge raw HTML payloads into thought context, blowing budget |
+
+---
+
+## 🔄 The Circuit Breaker State Machine
+
+LongGuard adapts standard distributed systems circuit breaker patterns to LLM cognition:
+
+1. **`CLOSED` (Normal)**: All checks pass. The agent runs freely.
+2. **`REFLECTING` (Intervention)**: A loop was detected. LongGuard injects an automated **Reflect & Pivot prompt** instructing the agent:
+   > *"You have called {tool} {count} times with the same arguments. Stop. Try a different tool or synthesize your current findings."*
+3. **`HALF-OPEN` (Observation)**: The agent gets one chance to demonstrate progress following reflection.
+4. **`OPEN` (Graceful Termination)**: If the loop persists after reflection, LongGuard terminates execution cleanly, preserving full trace telemetry and token usage.
+
+---
+
+## 📊 LongGuard vs. LangGraph `recursion_limit`
+
+| Capability | LangGraph `recursion_limit` | LongGuard 🛡️ |
+|---|:---:|:---:|
+| **Detects Tool-Repeat Loops** | ❌ No | ✅ **Yes** |
+| **Detects Semantic Reasoning Loops** | ❌ No | ✅ **Yes** |
+| **Detects Sudden Cost / Token Spikes** | ❌ No | ✅ **Yes** |
+| **Auto-Injects Recovery Prompts** | ❌ No | ✅ **Yes** |
+| **Exit Behavior** | 💥 Unhandled Exception (`Crash`) | 🛡️ **Graceful State Preservation** |
+| **Run Reporting & Telemetry** | ❌ No | ✅ **JSON & Summary Reports** |
+| **Configurable Thresholds** | ❌ Single integer | ✅ **Granular `GuardConfig`** |
+
+---
+
+## ⚙️ Configuration at a Glance
+
+All behavior can be customized via `GuardConfig`:
+
+```python
+from longguard import GuardConfig
+
+config = GuardConfig(
+    # Loop Detection Sensitivity
+    tool_repeat_threshold=3,          # Number of repeated tool calls before reflection
+    tool_repeat_window=6,             # History window to examine
+    dead_end_threshold=5,             # Steps with no progress before triggering
+    token_velocity_multiplier=3.0,    # Spike multiplier vs rolling baseline
+
+    # Hard Safety Guardrails
+    max_tokens_per_run=50_000,        # Hard stop if agent burns > 50k tokens
+    max_steps=30,                     # Maximum steps permitted
+    max_reflections=2,                # Maximum recovery attempts before kill
+)
+```
+
+👉 *For detailed documentation on custom detectors, embedding backends, and LangSmith telemetry, see the [Full Documentation](https://endevsols.github.io/LongGuard/).*
+
+---
+
+## 🌐 Part of the EnDevSols AI Infrastructure Suite
+
+LongGuard works alongside our other open-source tools to secure production LLM pipelines:
+
+- [**LongParser**](https://github.com/ENDEVSOLS/LongParser) — Fast, privacy-first local document parser (PDF, DOCX, XLSX).
+- [**LongProbe**](https://github.com/ENDEVSOLS/LongProbe) — Sub-second RAG retrieval regression testing with pytest.
+- [**LongTracer**](https://github.com/ENDEVSOLS/LongTracer) — Post-generation hallucination detection & claim verification.
+- [**LongGuard**](https://github.com/ENDEVSOLS/LongGuard) — In-flight runtime cognitive circuit breaker & loop recovery.
+
+---
+
+## 🤝 Contributing & Community
+
+We love contributions!
+- Submit bug reports and feature ideas via [GitHub Issues](https://github.com/ENDEVSOLS/LongGuard/issues).
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for development environment setup and testing guidelines.
+
+## 📄 License
+
+LongGuard is open-source software released under the [MIT License](LICENSE).